Planned breaking changes for Rsbuild 2.0

[chenjiahan]

This topic is used to collect and discuss breaking changes planned for Rsbuild 2.0.

Please note that we do not have a clear timeline for Rsbuild 2.0 yet.

Related: web-infra-dev/rspack#9270

[chenjiahan]

Remove the built-in webpack-bundle-analyzer

In the early versions of Rsbuild, we built-in the webpack-bundle-analyzer package for bundle size analysis. Considering that Rsdoctor now supports analyzing bundle size, we can remove this built-in functionality from @rsbuild/core to reduce the install size.

Related:

• performance.bundleAnalyze
• Rsdoctor - Bundle analysis

[chenjiahan]

PR: #6911

[chenjiahan]

Re-design performance.chunkSplit

Related:

• Is there a reason why "split-by-experience" uses splitChunks.name as the default? #5820

[chenjiahan]

Remove deprecated APIs

Configuration

• Remove source.alias, use resolve.alias instead.
  • refactor!: remove deprecated source.alias configuration #6902
• Remove source.aliasStrategy, use resolve.aliasStrategy instead.
  • refactor!: remove deprecated source.aliasStrategy configuration #6903
• Remove performance.profile, use stats.toJson instead.
  • refactor!: remove performance.profile configuration #6910
• Remove webpackConfig from html.templateParameters, use rspackConfig instead.
  • refactor!: remove deprecated HTML template parameters #6909
• Remove htmlWebpackPlugin from html.templateParameters, use htmlPlugin instead.
  • refactor!: remove deprecated HTML template parameters #6909

JavaScript API

• Remove deprecated compiler parameter of rsbuild.build().
  • refactor!: remove compiler parameter from rsbuild.build() #6912
• Remove deprecated compiler parameter of rsbuild.startDevServer().
  • refactor!: remove compiler parameter from rsbuild.startDevServer() #6913

[chenjiahan]

Make core-js an optional peer dependency

Background

Currently, Rsbuild includes core-js as a default dependency and provides the output.polyfill option to inject polyfills automatically.

However, not all use cases require core-js. For example, projects like Rslib and Rstest rely on Rsbuild for building and testing but typically do not need runtime polyfills.

Plan

Change core-js from a direct dependency of @rsbuild/core to an optional peer dependency.

When users enable output.polyfill, they need to install core-js themselves:

npm i core-js

Rsbuild will load core-js from the user project. If it is missing, Rsbuild will show a clear error.

Benefits

• Smaller installation size: https://packagephobia.com/result?p=core-js
• Lower dependency and security surface
• Keeps the existing output.polyfill API unchanged

[chenjiahan]

PR: #6960

[chenjiahan]

Default host change to localhost

Changing Rsbuild’s default dev server host from 0.0.0.0 to localhost (127.0.0.1).

export default {
  server: {
    // old defaults
    host: '0.0.0.0',
    // new defaults
    host: 'localhost'
  },
}

This improves security by preventing unintended exposure of the dev server to the local network, reducing the risk of unauthorized access.

Ref: vercel/next.js#64650, https://vite.dev/config/server-options#server-host

[chenjiahan]

PR: #6940

[chenjiahan]

Drop support for Node.js 18

As Node.js 18 reached its end-of-life on April 30, 2025, Rsbuild 2.0 will no longer support this version. The minimum supported version will be Node.js 20.19.

[chenjiahan]

PR: #6914

[SyMind]

Do not minify Node bundles

For Node targets, production builds no longer enable minification by default.

Server bundles prioritize debuggability, clear stack traces, and stable runtime behavior over bundle size. Minification remains available as an explicit opt-in via output.minify: true

[chenjiahan]

PR: #6922

[chenjiahan]

Pure ESM package

@rsbuild/core is now published as a pure ESM package, and its CommonJS build output has been removed. This change only affects how Rsbuild itself is published, reducing the installation size by about 500 KB.

In Node.js 20 and later, the runtime natively supports loading ESM modules via require(). As a result, for most projects that use Rsbuild through its JavaScript API, this change should have no practical impact and does not require any code modifications.

[chenjiahan]

PR: #6918

[chenjiahan]

ESM Node bundles

Changes the default value of output.module to true when the target is 'node'.

To preserve the v1 behavior (outputting CommonJS bundles), set output.module to false:

// rsbuild.config.ts
export default {
  output: {
    module: false,
    target: 'node',
  },
};

[chenjiahan]

PR: #6950