[RFC] Integrate Rspack builtin:swc-loader

[9aoy]

1 . Summary

The current Rspack mode has the following issues when using swc translation:

• Cannot skip compile. Rspack natively supports TS /TSX/ JSX / JS translation logic (full translation), which can not be closed or skipped
  • Which made polyfill.usage、source.exclude、source.include can not be used
  • It is inconsistent with webpack mode behavior: webpack mode only translates the files under the project src by default, and rspack is full translation
• Cannot be extended, does not support adding custom SWC plugins
  • Functions such as transformLoadsh, styledComponents, removePropTypes cannot be used due to not supporting extended swc capabilities.

Based on this background, Rspack supports builtin:swc-loader and disable default transformation (to avoid multiple transformations). see: web-infra-dev/rspack#4070

This RFC will describe how to migrate to builtin:swc-loader in modern.js and support the above features, since Rspack supports builtin:swc-loader and disable default transformation.

2. Detailed design

Migration from default transformation to builtin:swc-loader will be divided into three stages:

1. Turn off default translation and migrate builtins functionality to builtin:swc-loader
   1. This phase will open Rspack disableTransformByDefault config and migrate builtins functionality to builtin:swc-loader
   2. It will also support polyfill.usage and source.exclude configuration.
2. Apply include rule
   1. This stage will support the source.include configuration, and the files outside the project, such as node_modules, will not be translated by default
   2. This change is a breaking change for existing users of Rspack mode, and we will talk about how to be compatible & guide users to migrate.
3. Extend swc capabilities, apply swc plugins
   1. Currently, Rspack does not support adding custom wasm plugins. So we won't discuss this feature in this RFC yet

2.1 Migrate builtins functionality to builtin:swc-loader

Configurations/plugins that need to be migrated and modified include:

• builderPluginSwc
  • builtins.decorator
  • builtins.presetEnv
  • builtins.pluginImport
• builderPluginReact
  • builtins.react
• Support configuration of source.exclude
• Support polyfill usage feature by configuring swc env.mode to usage and exclude core-js.

This stage will turn on the Rspack disableTransformByDefault & does not support switching back to the default translation, but the include rule does not apply and thus it should have no impact on users.

2.2 Apply include rule

• For js/ts rules, modern.js will default application include: [context.rootPath, {not: /node_modules/}] configuration. And supports reading the current project source.include configuration.

How to determine which third-party packages need to be added to source.includeafter migration?

Modern.js provides security.checkSyntax capabilities, support analyzes whether there is incompatible advanced syntax in the build artifacts under the current browser scope. If any incompatible syntax is found, detailed information will be printed on the terminal and you can add them to source.include.

Migration plan

We will not take breaking change for users until the Rspack 0.4.0 version is published. We will add a new configuration disableTransformByDefault to support it.

• The default behavior remains the same, consistent with the rspack upgrade policy, and is enabled by the disableTransformByDefault switch.
• The generator template & documentation example has this switch enabled by default.

import { appTools, defineConfig } from '@modern-js/app-tools';

export default defineConfig<'rspack'>({
  plugins: [
    appTools({
      bundler: 'experimental-rspack',
+      rspackFuture: {
+          disableTransformByDefault: true
+      }
    }),
  ],
});

• When the disableTransformByDefault is not enabled, it will prompt error/warning, indicating that the TransformByDefault will be deprecated. Please migrate as soon as possible.

warning: The default full transform behavior will be deprecate in rspack 0.4.0 version. Please enable `disableTransformByDefault: true` as soon as possible.

- If you want to downgrade the syntax, you can compile the corresponding module through the `source.include` config.
- If you do not know which modules should be added with downgrade, you can check by enabling `security.checkSyntax` config.

3. Drawbacks

Not translate the files outside the project(such as node_modules) is a breaking change for users who already use Rspack mode.
When we apply it by default. We should take some measures to avoid problems after users upgrade, including but not limited to progressive upgrades, giving upgrade announcements, etc.