#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:

• For projects using webpack v4 or earlier versions, you can refer to webpack - To v5 from v4 to understand the differences.
• For projects using create-react-app or CRACO, you can refer to Migrating Create React App.
• For projects using Vue CLI, you can refer to Rsbuild - Migrating from Vue CLI.

#Installing Rspack

Install Rspack in your project directory:

npm add @rspack/core @rspack/cli @rspack/dev-server -D

yarn add @rspack/core @rspack/cli @rspack/dev-server -D

pnpm add @rspack/core @rspack/cli @rspack/dev-server -D

bun add @rspack/core @rspack/cli @rspack/dev-server -D

deno add npm:@rspack/core npm:@rspack/cli npm:@rspack/dev-server -D

Both @rspack/cli and @rspack/dev-server are optional dependencies:

• If you are not using webpack-cli, no need to install @rspack/cli.
• If you are not using webpack-dev-server, no need to install @rspack/dev-server.

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

npm remove webpack webpack-cli webpack-dev-server

yarn remove webpack webpack-cli webpack-dev-server

pnpm remove webpack webpack-cli webpack-dev-server

bun remove webpack webpack-cli webpack-dev-server

deno remove npm:webpack npm:webpack-cli npm:webpack-dev-server

#Updating package.json

Update your build scripts to use Rspack instead of webpack, see CLI for more details.

{
  "scripts": {
-   "dev": "webpack serve",
-   "build": "webpack build",
+   "dev": "rspack dev",
+   "build": "rspack build",
+   "preview": "rspack preview",
  }
}

#Updating configuration

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

Rspack supports most webpack configuration options. See Configure Rspack for the complete list of supported options.

#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:

const webpack = require('webpack'); 
const { rspack } = require('@rspack/core'); 

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

See 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:

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:

- 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"
        ],
      }
    ]
  }
}

#tsconfig-paths-webpack-plugin

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

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:

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

module.exports = {
  plugins: [
    new ForkTsCheckerWebpackPlugin(),
    new TsCheckerRspackPlugin(),
  ],
};

#Loaders

Rspack is compatible with most webpack loaders, so existing loaders can typically be reused without changes.

For optimal performance and consistency, we recommend the following migrations where applicable:

#babel-loader

Migrate babel-loader to builtin:swc-loader to use Rspack's built-in SWC transform for better performance.

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.

• Replace @babel/preset-typescript with SWC's syntax: 'typescript' option:

module.exports = {
  module: {
    rules: [
      {
-        test: /\.(j|t)sx?$/,
+        test: /\.(j|t)s$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-            loader: 'babel-loader',
+            loader: 'builtin:swc-loader',
            options: {
-              presets: ['@babel/preset-typescript'],
+              jsc: {
+                parser: {
+                  syntax: 'typescript',
+                },
+              },
            },
          },
        ],
      },
    ],
  },
};

• Replace @babel/preset-react with SWC's jsc.transform.react option:

+const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  module: {
    rules: [
      {
        test: /\.(j|t)sx?$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-            loader: 'babel-loader',
+            loader: 'builtin:swc-loader',
            options: {
-              presets: ['@babel/preset-typescript', '@babel/preset-react'],
+              jsc: {
+                parser: {
+                  syntax: 'typescript',
+                  tsx: true,
+                },
+                transform: {
+                  react: {
+                    runtime: 'automatic',
+                    development: isDev,
+                    refresh: isDev,
+                  },
+                },
+              },
            },
          },
        ],
      },
    ],
  },
};

#swc-loader

When migrating external swc-loader to builtin:swc-loader, only the loader name changes to builtin:swc-loader; all the options remain exactly the same as your original swc-loader config.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(j|t)sx?$/,
        use: [
          {
            loader: 'swc-loader',
            loader: 'builtin:swc-loader',
          },
        ],
      },
    ],
  },
};

#file-loader

Migrate file-loader to Asset Modules with asset/resource.

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

#url-loader

Migrate url-loader to Asset Modules with asset/inline.

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

#raw-loader

Migrate raw-loader to Asset Modules with asset/source.

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