> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Announcing Rspack 0.4 _November 22, 2023_ ![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png) Rspack Team [](https://x.com/rspack_dev) @rspack_dev ## 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](https://rsbuild.rs/) 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](https://v0.rspack.rs/config/builtins) code transformation features, [target](/config/target.md), and custom [rules\[\].type](/config/module-rules.md#rulestype). 1. Removal of support for some [builtins](https://v0.rspack.rs/config/builtins) features: - [builtins.relay](https://v0.rspack.rs/config/builtins#builtinsrelay): moved to `rspackExperiments.relay` - [builtins.react](https://v0.rspack.rs/config/builtins#builtinsreact): moved to `jsc.transform.react` - [builtins.emotion](https://v0.rspack.rs/config/builtins#builtinsemotion): moved to `rspackExperiments.emotion` - [builtins.pluginImport](https://v0.rspack.rs/config/builtins#builtinspluginimport): moved to `rspackExperiments.import` - [builtins.decorator](https://v0.rspack.rs/config/builtins#builtinsdecorator): moved to `jsc.parser.decorators` - [builtins.presetEnv](https://v0.rspack.rs/config/builtins#builtinspresetenv): moved to `jsc.env` ```js title="rspack.config.mjs" 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` }, }, }, ], }, experiments: { rspackFuture: { disableTransformByDefault: true, }, }, }; ``` 2. [target](/config/target.md) will not downgrade user-side code(including `node_modules`) ```diff title="rspack.config.mjs" 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" + } } }, ], } }; ``` 3. Removed non-webpack compatible [rules\[\].type](/config/module-rules.md#rulestype) 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](https://v0.rspack.rs/config/experiments#experimentsrspackfuturedisabletransformbydefault) for the complete migration guide. Check out our previous discussion [here](https://github.com/web-infra-dev/rspack/discussions/4070). ### 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. ```diff title="rspack.config.mjs" + import { ReactRefreshRspackPlugin } 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 ReactRefreshRspackPlugin() ], }; ``` Checkout [here](/guide/integrations/react.md#fast-refresh) 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](https://www.npmjs.com/package/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](/config/resolve.md#resolvetsconfig) for details. To opt out of the new resolver, set `experiments.rspackFuture.newResolver` to `false`. ## Migration guide There is a [migrate example](https://github.com/rstackjs/rstack-examples/pull/2) 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` ```diff title=package.json { "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 ```js { 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](#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](#deprecating-builtinreactrefresh). ### Migrating builtin options to builtin plugins In v0.4.0, Rspack deprecated some of the builtin options and migrated them to [builtin plugins](/config/plugins.md). 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: ```diff title="rspack.config.mjs" + 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](/plugins/html-rspack-plugin.md): ```diff title="rspack.config.mjs" + 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: ```js title="rspack.config.mjs" 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](/plugins/copy-rspack-plugin.md). For the original `builtins.minifyOptions`, we provide [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md): ```js title="rspack.config.mjs" 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](/config/plugins.md) for migration, or completed according to the CLI prompts after upgrading to v0.4.0.