ContextQMD
Back to Rspack

Migrate from webpack

website/docs/en/guide/migration/webpack.mdx

2.0.110.7 KB
Original Source

import { PackageManagerTabs } from '@theme';

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

Install Rspack in your project directory:

<PackageManagerTabs command="add @rspack/core @rspack/cli @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:

<PackageManagerTabs command="remove webpack webpack-cli webpack-dev-server" />

Updating package.json

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

diff
{
  "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.

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

js
const webpack = require('webpack'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

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

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:

js
const CopyWebpackPlugin = require('copy-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

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

mini-css-extract-plugin

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

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

js
const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin'); // [!code --]

module.exports = {
  resolve: {
    plugins: [new TsconfigPathsPlugin({})], // [!code --]
    tsConfig: {}, // [!code ++]
  },
};

fork-ts-checker-webpack-plugin

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

js
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin'); // [!code --]
const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin'); // [!code ++]

module.exports = {
  plugins: [
    new ForkTsCheckerWebpackPlugin(), // [!code --]
    new TsCheckerRspackPlugin(), // [!code ++]
  ],
};

terser-webpack-plugin

For projects that use terser-webpack-plugin to minify JavaScript, we recommend switching to rspack.SwcJsMinimizerRspackPlugin for better build performance:

js
const TerserPlugin = require('terser-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  optimization: {
    minimizer: [
      new TerserPlugin(), // [!code --]
      new rspack.SwcJsMinimizerRspackPlugin(), // [!code ++]
      new rspack.LightningCssMinimizerRspackPlugin(),
    ],
  },
};

:::tip When you explicitly configure optimization.minimizer, Rspack's default minimizers are disabled, so we recommend keeping both JavaScript and CSS minimizers in the list. :::

css-minimizer-webpack-plugin

For projects that use css-minimizer-webpack-plugin to minify CSS, we recommend switching to rspack.LightningCssMinimizerRspackPlugin for better build performance:

js
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin(),
      new CssMinimizerPlugin(), // [!code --]
      new rspack.LightningCssMinimizerRspackPlugin(), // [!code ++]
    ],
  },
};

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.

diff
module.exports = {
  module: {
    rules: [
      {
-        test: /\.(j|t)sx?$/,
+        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-           loader: 'babel-loader',
+           loader: 'builtin:swc-loader',
+           options: {
+             detectSyntax: 'auto',
+           },
          },
        ],
      },
    ],
  },
};
diff
+const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-            loader: 'babel-loader',
+            loader: 'builtin:swc-loader',
            options: {
-              presets: ['@babel/preset-typescript', '@babel/preset-react'],
+              jsc: {
+                transform: {
+                  react: {
+                    runtime: 'automatic',
+                    development: isDev,
+                    refresh: isDev,
+                  },
+                },
+              },
+              detectSyntax: 'auto',
            },
          },
        ],
      },
    ],
  },
};

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.

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

file-loader

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

diff
 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.

diff
 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.

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