#Upgrading from v1 to v2

This document lists all breaking changes from Rsbuild 1.x to 2.0. Use it as a migration reference.

This guide is a work in progress. Content will be added incrementally as Rsbuild 2.0 beta evolves.

#Default browserslist updated

In Rsbuild 2.0, the default browserslist have been updated to better reflect the modern web platform baseline.

#Web target

The default web browserslist has moved to a more modern baseline, the new default corresponds to baseline widely available on 2025-05-01:

• Chrome 87 → 107
• Edge 88 → 107
• Firefox 78 → 104
• Safari 14 → 16

This change affects JavaScript and CSS transformations, as well as polyfill behavior.

If your project defines its own browserslist configuration, for example via .browserslistrc or package.json#browserslist, Rsbuild will continue to use it. The defaults only apply when no browserslist configuration is found.

To keep the previous behavior, create a .browserslistrc file in your project root:

chrome >= 87
edge >= 88
firefox >= 78
safari >= 14

#Node target

Rsbuild 2.0 also updates the default Node.js target. Since Node.js 18 reached end of life in April 2025, Rsbuild now defaults to Node 20+.

• Node 16 → 20

To keep the previous behavior, use output.overrideBrowserslist:

export default {
  output: {
    target: 'node',
    overrideBrowserslist: ['node >= 16'],
  },
};

#Node.js support

Rsbuild 2.0 requires Node.js 20.19+ or 22.12+, Node.js 18 is no longer supported.

#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(esm). 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.

This does not affect Rsbuild's ability to build CommonJS output. All related build behavior and configuration options remain unchanged.

#Polyfill dependency change

core-js has been changed from a default dependency of @rsbuild/core to an optional peer dependency, which reduces the installation size by 1.2 MB.

If you enabled output.polyfill, install core-js v3 in your project:

npm add core-js

yarn add core-js

pnpm add core-js

bun add core-js

deno add npm:core-js

#Configuration

#Default server host

The default value of server.host has changed from '0.0.0.0' to 'localhost'.

This change prevents the dev server from being exposed to the local network by default, ensuring "secure by default" behavior.

If you need to access the server from other devices on the same network (e.g., for mobile testing), you can manually set the host to '0.0.0.0':

export default {
  server: {
    host: '0.0.0.0',
  },
};

Alternatively, you can use the --host CLI flag to enable network access on demand:

rsbuild dev --host

#Node output

When output.target is set to node, Rsbuild 2.0 defaults to ESM output via output.module and keeps output.minify disabled. In Rsbuild 1.x, the default was CommonJS output with minification enabled.

This keeps Node bundles aligned with modern ESM conventions while preserving clearer stack traces for debugging.

As a result, your runtime needs to load ESM bundles (for example, set "type": "module" in package.json or use .mjs output) unless you opt back into CommonJS.

To restore v1 behavior, explicitly disable ESM output and enable minification:

export default {
  output: {
    target: 'node',
    module: false,
    minify: true,
  },
};

#Remove source.alias

The deprecated source.alias option has been removed. Use resolve.alias instead.

export default {
- source: {
+ resolve: {
    alias: {
      '@': './src',
    },
  },
};

#Remove source.aliasStrategy

The deprecated source.aliasStrategy option has been removed. Use resolve.aliasStrategy instead.

export default {
- source: {
+ resolve: {
    aliasStrategy: 'prefer-alias',
  },
};

#Remove performance.bundleAnalyze

The deprecated performance.bundleAnalyze option has been removed.

In earlier versions, Rsbuild bundled webpack-bundle-analyzer by default. Rsdoctor now provides built-in bundle size analysis, so this functionality no longer needs to live inside @rsbuild/core. Removing it also helps reduce the installation size.

Use Rsdoctor to analyze bundle size, or register webpack-bundle-analyzer yourself via tools.rspack:

import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';

export default {
  tools: {
    rspack: {
      plugins: [
        new BundleAnalyzerPlugin({
          analyzerMode: 'static',
        }),
      ],
    },
  },
};

#Remove performance.profile

The performance.profile option has been removed. If you relied on it to emit a stats JSON file, use stats.toJson() in a custom plugin instead:

import { writeFileSync } from 'node:fs';
import { join } from 'node:path';

const statsJsonPlugin = {
  name: 'stats-json-plugin',
  setup(api) {
    api.onAfterBuild(({ stats }) => {
      writeFileSync(
        join(api.context.distPath, 'stats.json'),
        JSON.stringify(stats?.toJson({}), null, 2),
      );
    });
  },
};

export default {
  plugins: [statsJsonPlugin],
};

#Remove HTML template parameters

The deprecated template parameters have been removed from html.templateParameters

• webpackConfig: use rspackConfig instead.
• htmlWebpackPlugin: use htmlPlugin instead.

#JavaScript API

• Removed the deprecated compiler parameter from rsbuild.build().
• Removed the deprecated compiler parameter from rsbuild.startDevServer().
• Removed the deprecated content-changed message type from sockWrite, use static-changed instead.

#Dropping webpack support

Rsbuild 2.0 no longer supports using webpack as the bundler. In Rsbuild 1.x, this capability was mainly used to validate compatibility between Rspack and webpack. As Rspack has gradually matured and stabilized, this purpose is no longer necessary, so the related support has been removed.

The specific changes are as follows:

• Removed the @rsbuild/webpack package.
• Removed the @rsbuild/plugin-webpack-swc package.
• Removed the provider configuration option.
• Removed the tools.webpack and tools.webpackChain configuration options.
• Removed the api.modifyWebpackChain and api.modifyWebpackConfig plugin hooks.
• Removed the webpack type from the api.context.bundlerType.
• Removed webpack-related types.