November 02, 2023

#Announcing Rspack 0.4

#Major changes

#Drop Node.js 14 support

Rspack no longer supports Node.js 14, Node.js 16+ is now required.

#Make @rspack/core as peer dependency of @rspack/cli

@rspack/core is now a peer dependency of @rspack/cli rather than a direct dependency. This means that you need to manually install @rspack/core with @rspack/cli now. aligning Rspack more closely with webpack. In the long term, the positioning of @rspack/cli will no longer be an out-of-the-box solution. We will align @rspack/cli with webpack-cli and may even directly support the use of @rspack/core in webpack-cli. We recommend Rsbuild as an out-of-the-box solution.

#Deprecating default transformation

experiments.rspackFuture.disableTransformByDefault is enabled by default in v0.4.0. For people that still need the legacy behavior, you may manually set this option to false.

This feature primarily addresses three categories of problems: builtins code transformation features, target, and custom Rule.type.

1. Removal of support for some builtins features:

• builtins.relay: moved to rspackExperiments.relay
• builtins.react: moved to jsc.transform.react
• builtins.emotion: moved to rspackExperiments.emotion
• builtins.pluginImport: moved to rspackExperiments.import
• builtins.decorator: moved to jsc.parser.decorators
• builtins.presetEnv: moved to jsc.env

export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'ecmascript',
              jsx: true,
            },
            transform: {
              react: {
                runtime: 'automatic',
              },
            },
          },
          rspackExperiments: {
            emotion: true, // The same as `builtins`
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
  experiments: {
    rspackFuture: {
      disableTransformByDefault: true,
    },
  },
};

2. target will not downgrade user-side code(including node_modules)

export default {
  target: ["web", "es5"],
  module: {
    rules: [
      {
        test: /\.[cm]?js$/,
        exclude: /node_modules/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: "ecmascript"
            },
+           target: "es5" // Notice: `jsc.target` and `env` cannot be set at the same time.
          },
+        env: { //  Notice: `jsc.target` and `env` cannot be set at the same time.
+         targets: "chrome >= 48"
+        }
        }
        type: 'javascript/auto',
      },
    ],
  }
};

3. Removed non-webpack compatible Rule.type

These types have been removed:

• "typescript"
• "jsx"
• "tsx"

For JS-related types, only the following will be retained:

• "javascript/auto"
• "javascript/esm"
• "javascript/dynamic"

Refer to this for the complete migration guide.

Check out our previous discussion here.

#Deprecating builtin.react.refresh

With experiments.rspackFuture.disableTransformByDefault is enabled by default in v0.4.0, builtin.react.refresh has also been deprecated. Now we recommend using @rspack/plugin-react-refresh to enable react fast refresh.

+ import ReactRefreshPlugin from '@rspack/plugin-react-refresh';

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

export default {
  // ...
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
+                  development: isDev,
+                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
-  builtins: {
-    react: {
-      refresh: true,
-    }
-  },
  plugins: [
+    isDev && new ReactRefreshPlugin()
  ],
};

Checkout here for more details.

#Deprecating builtin:sass-loader

builtin:sass-loader has now been deprecated. If you are using it, migrate to sass-loader. Rspack will remove builtin:sass-loader in v0.5.0.

#Deprecating experiments.incrementalRebuild

experiments.incrementalRebuild has now been deprecated. Rspack will remove it in v0.5.0.

#Refactoring export API in @rspack/core

Before, some APIs should not be exported accidentally exported through re-export from @rspack/core. Now with this refactor, we clean up the export APIs from @rspack/core.

This shouldn't break anything, but if you are using unintentionally exported APIs, this may break you, and you may be using Rspack in the hacky way.

If there is a real need for removed APIs from this refactor, please raise an issue in the Rspack repository.

#Deprecating builtins.devFriendlySplitChunks and experiments.newSplitChunks

In order to full migrate to Webpack's split chunks implementation, these fields are deprecated. Rspack will remove these fields in v0.5.0.

#Enable newResolver by default

New resolver is now enabled by default.

The new resolver has passed all of enhanced-resolve's test suite. It is 5 times faster than previous implementation, and 28 times faster than enhanced-resolve.

The new resolver can be configured to read tsconfig.json's compilerOptions.paths and references field and provides better support for nested path alias. See API resolve.tsConfig for details.

To opt out of the new resolver, set experiments.rspackFuture.newResolver to false.

#Migration guide

There is a migrate example demonstrating how to migrate from Rspack 0.3.14 to Rspack 0.4.0.

#Choose @rspack/cli or Rsbuild?

If your application is a CSR application, we strongly encourage you to use Rsbuild instead of configuring Rspack yourself, as Rsbuild is much easier to use compared to @rspack/cli.

#Upgrade Node.js version

Rspack no longer supports Node.js 14 as of version 0.4.0; Node.js 16+ is now required.

#Install @rspack/core manually with @rspack/cli

{
  "devDependencies": {
+    "@rspack/core": "0.4.0",
     "@rspack/cli": "0.4.0"
  }
}

#Use builtin:swc-loader to support module transformation

Rspack no longer transforms files by default as of version 0.4.0, you can still enable old transform behavior by the following setting

{
  experiments: {
    rspackFuture: {
      disableTransformByDefault: false; // set to old transform behavior
    }
  }
}

But we suggest you use builtin:swc-loader to transform files now. More details are available in Deprecating Default Transformation.

#Use @rspack/plugin-react-refresh for React applications

builtin.react.refresh does not work when we disable the default transformation, so you need to use @rspack/plugin-react-refresh to enable fast refresh. More details are available in Deprecating builtin.react.refresh.

#Migrating builtin options to builtin plugins

In v0.4.0, Rspack deprecated some of the builtin options and migrated them to builtin plugins.

Currently, Rspack's internal plugins are divided into two categories:

• Plugins compatible with Webpack, such as DefinePlugin, ProvidePlugin, etc. This part has been fully aligned with webpack.
• Rspack-specific plugins, such as SwcJsMinimizerRspackPlugin, CopyRspackPlugin, etc.

The original builtins.define can be migrated as follows:

+ import { rspack } from '@rspack/core';

export default {
-  builtins: {
-    define: { process.env.NODE_ENV: JSON.stringify(process.env.NODE_ENV) }
-  },
+  plugins: [
+    new rspack.DefinePlugin({ process.env.NODE_ENV: JSON.stringify(process.env.NODE_ENV) })
+  ]
}

For builtins.html, it can be directly migrated to HtmlRspackPlugin:

+ import { rspack } from '@rspack/core';

export default {
-  builtins: {
-    html: [{ template: "./index.html" }]
-  },
+  plugins: [
+    new rspack.HtmlRspackPlugin({ template: "./index.html" })
+  ]
}

When there are multiple configurations in builtins.html, multiple plugin instances can be created:

import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({ template: './index.html' }),
    new rspack.HtmlRspackPlugin({ template: './foo.html' }),
  ],
};

For builtins.copy, it can be directly migrated to CopyRspackPlugin.

For the original builtins.minifyOptions, we provide SwcJsMinimizerRspackPlugin:

import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        // minimizer configuration
      }),
    ],
  },
};

Other builtin options can be directly referred to the rspack builtin plugins for migration, or completed according to the CLI prompts after upgrading to v0.4.0.