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

#Cache configuration

Webpack and Rspack use different cache option shapes. Do not copy webpack cache options directly; map them to the corresponding Rspack cache options.

Disabled cache and memory cache can be kept as-is: cache: false, cache: true, and cache: { type: 'memory' } have the same meaning in Rspack.

For webpack filesystem cache, use Rspack persistent cache, then migrate the supported fields below.

1. Change webpack cache.type: 'filesystem' to Rspack cache.type: 'persistent'.

export default {
- cache: {
-   type: 'filesystem',
- },
+ cache: {
+   type: 'persistent',
+ },
};

2. Flatten webpack cache.buildDependencies into Rspack cache.buildDependencies, which accepts a file path array.

export default {
- cache: {
-   buildDependencies: {
-     config: [__filename, path.join(__dirname, 'package.json')],
-     ts: [path.join(__dirname, 'tsconfig.json')]
-   }
- },
+ cache: {
+   type: 'persistent',
+   buildDependencies: [
+     __filename,
+     path.join(__dirname, 'package.json'),
+     path.join(__dirname, 'tsconfig.json')
+   ]
+ },
};

3. Merge webpack cache.name and cache.version into Rspack cache.version.

Rspack does not have a separate cache.name option. Cache instances are isolated by cache.version and cache.storage.directory.

export default {
- cache: {
-   name: `${config.name}-${config.mode}-${otherFlags}`,
-   version: appVersion
- },
+ cache: {
+   type: 'persistent',
+   version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
+ },
};

4. Move webpack top-level snapshot options into Rspack cache.snapshot.

export default {
- snapshot: {
-   immutablePaths: [path.join(__dirname, 'constant')],
-   managedPaths: [path.join(__dirname, 'node_modules')],
-   unmanagedPaths: []
- },
+ cache: {
+   type: 'persistent',
+   snapshot: {
+     immutablePaths: [path.join(__dirname, 'constant')],
+     managedPaths: [path.join(__dirname, 'node_modules')],
+     unmanagedPaths: []
+   }
+ },
};

5. Move webpack cache.cacheDirectory to Rspack cache.storage.directory.

export default {
- cache: {
-   cacheDirectory: path.join(__dirname, 'node_modules/.cache/test')
- },
+ cache: {
+   type: 'persistent',
+   storage: {
+     type: 'filesystem',
+     directory: path.join(__dirname, 'node_modules/.cache/test')
+   }
+ },
};

The following example shows the same mapping when automating config migration:

function transform(webpackConfig, rspackConfig) {
  if (webpackConfig.cache === undefined) {
    webpackConfig.cache = webpackConfig.mode === 'development';
  }

  if (!webpackConfig.cache) {
    rspackConfig.cache = false;
    return;
  }

  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
    rspackConfig.cache = true;
    return;
  }

  rspackConfig.cache = { type: 'persistent' };

  rspackConfig.cache.buildDependencies = Object.values(
    webpackConfig.cache.buildDependencies || {},
  ).flat();

  const version = [webpackConfig.cache.name, webpackConfig.cache.version]
    .filter(Boolean)
    .join('-');
  if (version) {
    rspackConfig.cache.version = version;
  }

  rspackConfig.cache.snapshot = {
    immutablePaths: webpackConfig.snapshot?.immutablePaths,
    managedPaths: webpackConfig.snapshot?.managedPaths,
    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
  };

  if (webpackConfig.cache.cacheDirectory) {
    rspackConfig.cache.storage = {
      type: 'filesystem',
      directory: webpackConfig.cache.cacheDirectory,
    };
  }
}

#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(),
  ],
};

#terser-webpack-plugin

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

const TerserPlugin = require('terser-webpack-plugin'); 
const { rspack } = require('@rspack/core'); 

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

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

const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); 
const { rspack } = require('@rspack/core'); 

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

#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 builtin:swc-loader using detectSyntax: 'auto':

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',
+           },
          },
        ],
      },
    ],
  },
};

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

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

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

#Common webpack package replacements

When migrating webpack ecosystem packages, the following non-plugin packages usually need to be replaced.

For plugin packages, see Plugin compatibility.