close
Guide
Config
Plugin
API
Blog
About
Contribute
Guide
Config
Plugin
API
Blog
About
Contribute

Builtin swc-loader

builtin:swc-loader is the Rust version of swc-loader, aiming to deliver better performance. The Loader's configuration is aligned with the JS version of swc-loader.

Example

If you need to use builtin:swc-loader in your project, configure it as follows:

TypeScript Transpilation

To transpile .ts files:

module.exports = {
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};

JSX Transpilation

To transpile React's .jsx files:

module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
                  pragma: 'React.createElement',
                  pragmaFrag: 'React.Fragment',
                  throwIfNamespace: true,
                  development: false,
                  useBuiltins: false,
                },
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};

Syntax Lowering

SWC provides jsc.target and env.targets to specify the target of JavaScript syntax lowering.

jsc.target

jsc.target is used to specify the ECMA version, such as es5, es2015, es2016, etc.

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              target: 'es2015',
            },
            // ...other options
          },
        },
      },
    ],
  },
};

env.targets

env.targets uses the browserslist syntax to specify browser range, for example:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            env: {
              targets: [
                'chrome >= 87',
                'edge >= 88',
                'firefox >= 78',
                'safari >= 14',
              ],
            },
            // ...other options
          },
        },
      },
    ],
  },
};
TIP

jsc.target and env.targets cannot be configured at the same time, choose one according to your needs.

Polyfill Injection

When using higher versions of JavaScript syntax and APIs in your project, to ensure that the compiled code can run in lower version browsers, you will typically need to perform two parts of the downgrade: syntax downgrading and polyfill injection.

SWC supports injecting core-js as an API polyfill, which can be configured using env.mode and env.coreJs:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            env: {
              mode: 'usage',
              coreJs: '3.26.1',
              targets: [
                'chrome >= 87',
                'edge >= 88',
                'firefox >= 78',
                'safari >= 14',
              ],
            },
            // ...other options
          },
        },
      },
    ],
  },
};

Type declaration

You can enable type hints using the SwcLoaderOptions type exported by @rspack/core:

  • rspack.config.js:
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          /** @type {import('@rspack/core').SwcLoaderOptions} */
          options: {
            // some options
          },
        },
      },
    ],
  },
};
  • rspack.config.ts:
import type { SwcLoaderOptions } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            // some options
          } satisfies SwcLoaderOptions,
        },
      },
    ],
  },
};

Options

The following is an introduction to some SWC configurations and Rspack specific configurations. Please refer to the SWC Configurations for the complete options.

jsc.experimental.plugins

Stability: Experimental
WARNING

The Wasm plugin is deeply coupled with the version of SWC, you need to choose a Wasm plugin that is compatible with the corresponding version of SWC in order to function normally.selecting-swc-core.

you can see more compatible info about how to choose right Wasm plugin version in

Rspack supports load Wasm plugin in builtin:swc-loader, you can specify the plugin name like

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              experimental: {
                plugins: [
                  [
                    '@swc/plugin-remove-console',
                    {
                      exclude: ['error'],
                    },
                  ],
                ],
              },
            },
          },
        },
      },
    ],
  },
};

this is an example of Wasm plugin usage.

Set cache root

When you use SWC's Wasm plugin, SWC will generate cache files in the .swc directory of the current project by default. If you want to adjust this directory, you can modify the cacheRoot configuration, such as:

const path = require('path');

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              experimental: {
                cacheRoot: path.join(__dirname, './node_modules/.cache/swc'),
              },
            },
          },
        },
      },
    ],
  },
};

rspackExperiments

Experimental features provided by rspack.

rspackExperiments.import

Stability: Experimental

Ported from babel-plugin-import, configurations are basically the same.

Function can't be used in configurations, such as customName, customStyleName, they will cause some performance overhead as these functions must be called from Rust , inspired by modularize_imports, some simple function can be replaced by template string instead. Therefore, the function type configuration such as customName, customStyleName can be passed in strings as templates to replace functions and improve performance.

For example:

import { MyButton as Btn } from 'foo';

Apply following configurations:

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        use: 'builtin:swc-loader',
        options: {
          ...
          rspackExperiments: {
            import: [{
               libraryName: 'foo',
               customName: 'foo/es/{{ member }}',
            }]
          }
        }
      }
    ]
  }
};

{{ member }} will be replaced by the imported specifier:

import Btn from 'foo/es/MyButton';

Template customName: 'foo/es/{{ member }}' is the same as customName: (member) => `foo/es/${member}` , but template string has no performance overhead of Node-API.

The template used here is handlebars. There are some useful builtin helpers, Take the above import statement as an example:

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        use: 'builtin:swc-loader',
        options: {
          ...
          rspackExperiments: {
            import: [{
               libraryName: 'foo',
               customName: 'foo/es/{{ kebabCase member }}',
            }]
          }
        }
      }
    ]
  }
};

Transformed to:

import Btn from 'foo/es/my-button';

In addition to kebabCase, there are camelCase, snakeCase, upperCase, lowerCase and legacyKebabCase/legacySnakeCase can be used as well.

The legacyKebabCase/legacySnakeCase works as babel-plugin-import versions before 1.13.7.

You can check the document of babel-plugin-import for other configurations.

Taking the classic 4.x version of ant-design as an example, we only need to configure it as follows:

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        use: 'builtin:swc-loader',
        options: {
          ...
          rspackExperiments: {
            import: [
              {
                libraryName: 'antd',
                style: '{{member}}/style/index.css',
            },
            ]
          }
        }
      }
    ]
  }
};

The above configuration will transform import { Button } from 'antd'; to:

import Button from 'antd/es/button';
import 'antd/es/button/style/index.css';

Then you can see the style file is automatically imported and applied on the page.

Of course, if you have already configured support for less, you can simply use the following configuration:

rspack.config.js
module.exports = {
  module: {
    rules: [
      {
        use: 'builtin:swc-loader',
        options: {
          ...
          rspackExperiments: {
            import: [
              {
                libraryName: 'antd',
                style: true,
            },
            ]
          }
        }
      }
    ]
  }
};

The above configuration will transform import { Button } from 'antd'; to:

import Button from 'antd/es/button';
import 'antd/es/button/style';