close
Guide
Config
Plugin
API
Blog
About
Contribute
Guide
Config
Plugin
API
Blog
About
Contribute

Migrate from webpack

Rspack's configuration is designed based on webpack, enabling you to migrate your project from webpack to Rspack with ease.

This document is primarily aimed at projects using webpack 5. Since Rspack's API and configuration align with webpack 5. For projects not using webpack 5, there are other migration guides that can be referenced:

Installing Rspack

In your project directory, install Rspack as a devDependencies:

npm
yarn
pnpm
bun
npm add @rspack/core @rspack/cli -D

Now you can remove the webpack-related dependencies from your project:

npm
yarn
pnpm
bun
npm remove webpack webpack-cli webpack-dev-server
TIP

In some cases, you will still need to keep webpack as a dev dependency, such as when using vue-loader.

This is because these packages directly import subpaths of webpack and couple with webpack. If you encounter this issue, you can provide feedback to the maintainers of these plugins, asking them if they can make webpack an optional dependency.

Updating package.json

Update your build scripts to use Rspack instead of webpack:

package.json
{
  "scripts": {
-   "serve": "webpack serve",
-   "build": "webpack build",
+   "serve": "rspack serve",
+   "build": "rspack build",
  }
}

Updating configuration

Rename the webpack.config.js file to rspack.config.js.

TIP

Rspack commands can specify the configuration file with -c or --config, similar to webpack commands. However, unlike webpack, if a configuration file is not explicitly specified, Rspack defaults to using rspack.config.js.

Rspack does not currently support all webpack configurations, and some configurations might affect the build output. To ensure the correctness of the build output, Rspack enables strict validation of the configurations by default. However, Rspack also provides a loose mode for easy progressive migration. You can enable it by setting the RSPACK_CONFIG_VALIDATE environment variable:

# Enable loose validation mode will print out erroneous configurations but will not throw error.
RSPACK_CONFIG_VALIDATE=loose rspack build
# Enable loose validation mode, without printing errors or throwing error.
RSPACK_CONFIG_VALIDATE=loose-silent rspack build

Rspack is actively working on implementing webpack's upcoming features, so some configuration defaults differ from webpack 5, as shown below:

Configuration webpack Default Rspack Default
node.global true 'warn'
node.__filename 'mock' 'warn-mock'
node.__dirname 'mock' 'warn-mock'

You can refer to Configure Rspack to see the configurations supported by Rspack.

Webpack built-in plugins

Rspack has implemented most of webpack's built-in plugins, with the same names and configuration parameters, allowing for easy replacement.

For example, replacing the DefinePlugin:

rspack.config.js
- const webpack = require('webpack');
+ const rspack = require('@rspack/core');

module.exports = {
  //...
  plugins: [
-   new webpack.DefinePlugin({
+   new rspack.DefinePlugin({
      // ...
    }),
  ],
}

See Webpack-aligned built-in plugins for more information about supported webpack plugins in Rspack.

Community plugins

Rspack supports most of the webpack community plugins and also offers alternative solutions for some currently unsupported plugins.

Check Plugin compat for more information on Rspack's compatibility with popular webpack community plugins.

copy-webpack-plugin

Use rspack.CopyRspackPlugin instead of copy-webpack-plugin:

rspack.config.js
- const CopyWebpackPlugin = require('copy-webpack-plugin');
+ const rspack = require('@rspack/core');

module.exports = {
  plugins: [
-   new CopyWebpackPlugin({
+   new rspack.CopyRspackPlugin({
      // ...
    }),
  ]
}

mini-css-extract-plugin

Use rspack.CssExtractRspackPlugin instead of mini-css-extract-plugin:

rspack.config.js
- const CssExtractWebpackPlugin = require('mini-css-extract-plugin');
+ const rspack = require('@rspack/core');

module.exports = {
  plugins: [
-   new CssExtractWebpackPlugin({
+   new rspack.CssExtractRspackPlugin({
      // ...
    }),
  ]
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
-         CssExtractWebpackPlugin.loader,
+         rspack.CssExtractRspackPlugin.loader,
          "css-loader"
        ],
+       type: 'javascript/auto'
      }
    ]
  }
}

tsconfig-paths-webpack-plugin

Use resolve.tsConfig instead of tsconfig-paths-webpack-plugin:

rspack.config.js
- const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  resolve: {
-   plugins: [new TsconfigPathsPlugin({})]
+   tsConfig: {}
  }
}

fork-ts-checker-webpack-plugin

Use ts-checker-rspack-plugin instead of fork-ts-checker-webpack-plugin:

rspack.config.js
- const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
+ const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');

module.exports = {
  plugins: [
-   new ForkTsCheckerWebpackPlugin()
+   new TsCheckerRspackPlugin()
  ]
}

Loaders

Rspack's loader runner is fully compatible with webpack's loader functionality, supporting the vast majority of webpack loaders. You can use your existing loaders without any changes. However, to achieve the best performance, consider migrating the following loaders:

babel-loader / swc-loader → builtin:swc-loader

Using builtin:swc-loader offers better performance compared to the babel-loader and the external swc-loader, as it avoids frequent communication between JavaScript and Rust.

If you need custom transformation logic using Babel plugins, you can retain babel-loader, but it is recommended to limit its use to fewer files to prevent significant performance degradation.

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.tsx?$/i,
-        use: [
-          {
-            loader: 'babel-loader',
-            options: {
-              presets: ['@babel/preset-typescript'],
-            },
-          },
-        ],
-        test: /\.jsx?$/i,
-        use: [
-          {
-            loader: 'babel-loader',
-            options: {
-              presets: ['@babel/preset-react'],
-            },
-          },
-        ],
-      },
+      {
+        test: /\.(j|t)s$/,
+        exclude: [/[\\/]node_modules[\\/]/],
+        loader: 'builtin:swc-loader',
+        options: {
+          jsc: {
+            parser: {
+              syntax: 'typescript',
+            },
+            externalHelpers: true,
+            transform: {
+              react: {
+                runtime: 'automatic',
+                development: !prod,
+                refresh: !prod,
+              },
+            },
+          },
+          env: {
+            targets: 'Chrome >= 48',
+          },
+        },
+      },
+      {
+        test: /\.(j|t)sx$/,
+        loader: 'builtin:swc-loader',
+        exclude: [/[\\/]node_modules[\\/]/],
+        options: {
+          jsc: {
+            parser: {
+              syntax: 'typescript',
+              tsx: true,
+            },
+            transform: {
+              react: {
+                runtime: 'automatic',
+                development: !prod,
+                refresh: !prod,
+              },
+            },
+            externalHelpers: true,
+          },
+          env: {
+            targets: 'Chrome >= 48', // browser compatibility
+          },
+        },
+      },
     ],
   },
 };

file-loader / url-loader / raw-loader → Asset Modules

Rspack implements Webpack 5's Asset Modules, using asset modules to replace file-loader, url-loader, and raw-loader for better performance.

file-loader → asset/resource

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.(png|jpe?g|gif)$/i,
-        use: ["file-loader"],
-      },
+      {
+        test: /\.(png|jpe?g|gif)$/i,
+        type: "asset/resource",
+      },
     ],
   },
 };

url-loader → asset/inline

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.(png|jpe?g|gif)$/i,
-        use: ["url-loader"],
-      },
+      {
+        test: /\.(png|jpe?g|gif)$/i,
+        type: "asset/inline",
+      },
     ],
   },
 };

raw-loader → asset/source

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /^BUILD_ID$/,
-        use: ["raw-loader",],
-      },
+      {
+        test: /^BUILD_ID$/,
+        type: "asset/source",
+      },
     ],
   },
 };