Modern.js Builder#

This chapter introduces how to migrate a Modern.js Builder (or EdenX Builder) project to Rsbuild.

Key Differences#

Rsbuild is the new version of Modern.js Builder, with the following key differences:

• Rsbuild has better performance. When using Rspack simultaneously, the startup speed and build speed of Rsbuild are 1.5 to 2 times faster than Builder.
• Rsbuild only supports Rspack as the bundler and no longer supports Webpack.
• Rsbuild's CLI tool and dev server are more powerful and support more features.

Installing Dependencies#

First, you need to replace the npm dependencies related to Builder with Rsbuild's dependencies.

• Remove Builder's dependencies:

npm remove @modern-js/builder-cli @modern-js/builder-webpack-provider @modern-js/builder-rspack-provider

• Install Rsbuild's dependencies:

npm add @rsbuild/core -D

Updating npm Scripts#

Next, you need to update the npm scripts in the package.json to Rsbuild's CLI commands.

{
  "scripts": {
-   "dev": "builder dev",
-   "build": "builder build",
-   "serve": "builder serve"
+   "dev": "rsbuild dev",
+   "build": "rsbuild build",
+   "preview": "rsbuild preview"
  }
}

Modifying Configuration Files#

• Rename builder.config.ts to rsbuild.config.ts.
• Change the import of the defineConfig method from @modern-js/builder-cli to @rsbuild/core.
• Change the builderPlugins field to plugins.

- import { defineConfig } from '@modern-js/builder-cli';
+ import { defineConfig } from '@rsbuild/core';

export default defineConfig({
-  builderPlugins: [],
+  plugins: [],
});

Replacing Plugins#

Rsbuild and Builder have incompatible plugin systems, so you need to replace Builder's plugins with Rsbuild's plugins.

The following table shows the correspondence between Builder plugins and Rsbuild plugins:

For example, if you were using @modern-js/builder-plugin-vue, you need to first install @rsbuild/plugin-vue, then import the plugin in rsbuild.config.ts and add it to the plugins field.

- import { builderPluginVue } from '@modern-js/builder-plugin-vue';
+ import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
-  builderPlugins: [builderPluginVue()],
+  plugins: [pluginVue()],
});

Add React-related Plugins#

Rsbuild is not coupled with any front-end UI framework. Therefore, if you are a React project, you need to manually add React Plugin:

import { pluginReact } from '@rsbuild/plugin-react';

export default {
  plugins: [pluginReact()],
};

If you are using SVGR in your current project, you also need to register SVGR Plugin:

import { pluginSvgr } from '@rsbuild/plugin-svgr';

export default {
  plugins: [pluginSvgr()],
};

If you are a user of other frameworks, you can refer to Rsbuild Plugin List to select the corresponding framework plugin.

Configuration Migration#

Most configs in Rsbuild and Builder are consistent, with only a few adjustments.

You can refer to the Rsbuild options to view the configs of Rsbuild.

It is worth noting that, compared to Builder, there are some differences in default values and behaviors in Rsbuild:

• Browserslist: The default is minimum compatible with browsers that support Native ES Modules, refer to Default Browserslist.
• HTML file output path: default output to the root of dist directory, refer to Default Directory Structure.
• Polyfill injection method: Inject on demand by default, refer to output.polyfill.
• TypeScript type check: not enabled by default, you need to manually register the Type Check Plugin.
• Modify DevServer configuration: Modify dev and server configuration instead.

Validating Results#

After completing the above steps, you have migrated from Modern.js Builder to Rsbuild. You can now try starting the dev server by running the npm run dev command.

If you encounter any issues during the build process, please debug according to the error logs.

Contents Supplement#

The current document only covers part of the migration process. If you find suitable content to add, feel free to contribute to the documentation via pull request 🤝.

The documentation for rsbuild can be found in the rsbuild/packages/document directory.