# Babel plugin

import { pluginBabel } from '@rsbuild/plugin-babel';
export default {
  plugins: [pluginBabel()],
#Compilation cache
After using the Babel plugin, Rsbuild will perform the Babel transpilation in addition to the standard SWC transpilation, which adds additional compilation overhead. This can cause a noticeable decrease in build speed.
To reduce the overhead of Babel transpilation, the @rsbuild/plugin-babel enables Babel compilation cache by default. If you want to disable the cache, you can set performance.buildCache to false:
rsbuild.config.ts
export default {
  performance: {
    buildCache: false,
#Options
#babelLoaderOptions
Options passed to babel-loader, please refer to the babel-loader documentation for detailed usage.
Type: Object | Function
Default:
const defaultOptions = {
  babelrc: false




    
,
  compact: false,
  configFile: false,
  plugins: [
    ['@babel/plugin-proposal-decorators', config.source.decorators],
    ...(isLegacyDecorators ? ['@babel/plugin-transform-class-properties'] : []),
  presets: [
      '@babel/preset-typescript',
        allExtensions: true,
        allowDeclareFields: true,
        allowNamespaces: true,
        isTSX: true,
        optimizeConstEnums: true,
#Function type
When configuration is of type Function, the default Babel configuration will be passed as the first parameter. You can directly modify the configuration object or return an object as the final babel-loader configuration.
pluginBabel({
  babelLoaderOptions: (config) => {
    // Add a Babel plugin
    // note: the plugin have been added to the default config to support antd load on demand
    config.plugins ||= [];
    config.plugins.push([
      'babel-plugin-import',
        libraryName: 'my-components',
        libraryDirectory: 'es',
        style: true,
The second parameter of the function provides some more convenient utility functions. Please continue reading the documentation below.
The above example is just for reference, usually you do not need to manually configure babel-plugin-import, because the Rsbuild already provides a more general source.transformImport configuration.

#Object type
When configuration's type is Object, the config will be shallow merged with default config by Object.assign.
CAUTION

Note that Object.assign is a shallow copy and will completely overwrite the built-in presets or plugins array, please use it with caution.
pluginBabel({
  babelLoaderOptions: {
    plugins: [
        'babel-plugin-import',
          libraryName: 'my-components',
          libraryDirectory: 'es',
          style: true,
#Util functions
When configuration is a Function, the tool functions available for the second parameter are as follows:
#addPlugins
Type: (plugins: BabelPlugin[]) => void
Add some Babel plugins. For example:
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    addPlugins([
        'babel-plugin-import',
          libraryName: 'my-components',
          libraryDirectory: 'es',
          style: true,
#addPresets
Type: (presets: BabelPlugin[]) => void
Add Babel preset configuration. (No need to add presets in most cases)
pluginBabel({
  babelLoaderOptions: (config, { addPresets }) => {
    addPresets(['@babel/preset-env']);
#removePlugins
Type: (plugins: string | string[]) => void
To remove the Babel plugin, just pass in the name of the plugin to be removed, you can pass in a single string or an array of strings.
pluginBabel({
  babelLoaderOptions: (config, { removePlugins }) => {
    removePlugins('babel-plugin-import');
#removePresets
Type: (presets: string | string[]) => void
To remove the Babel preset configuration, pass in the name of the preset to be removed, you can pass in a single string or an array of strings.
pluginBabel({
  babelLoaderOptions: (config, { removePresets }) => {
    removePresets('@babel/preset-env');
#include
Type: string | RegExp | (string | RegExp)[]
Default: undefined
Used to specify the files that need to be compiled by Babel.
Due to the performance overhead of Babel compilation, matching only certain files through include can reduce the number of modules compiled by Babel, thereby improving build performance.
For example, to only compile .custom.js files and ignore files under node_modules:
pluginBabel({
  include: /\.custom\.js$/,
  // recommended to exclude the node_modules to improve build performance
  exclude: /[\\/]node_modules[\\/]/,
When you configure the include or exclude options, Rsbuild will create a separate Rspack rule to apply babel-loader and swc-loader.
This separate rule is completely independent of the SWC rule built into Rsbuild and is not affected by source.include and source.exclude.

#exclude
Type: string | RegExp | (string | RegExp)[]
Default: undefined
Used to specify the files that do not need to be compiled by Babel.
Due to the performance overhead of Babel compilation, excluding certain files through exclude can reduce the number of modules compiled by Babel, thereby improving build performance.
#Execution order
After using @rsbuild/plugin-babel, Rsbuild will use both babel-loader and builtin:swc-loader to compile JavaScript files, with Babel running before SWC.
This means that if you are using some new ECMAScript features in your code, you may need to add Babel plugins to ensure that Babel can correctly compile these new features.
For example, add the @babel/plugin-transform-private-methods plugin to enable Babel to correctly compile private properties:
pluginBabel({
  babelLoaderOptions: {
    plugins: ['@babel/plugin-transform-private-methods'],
#Debugging configs
After modifying the babel-loader configuration, you can view the final generated configuration in Rsbuild debug mode.
First, enable debug mode by using the DEBUG=rsbuild option:
# Debug development mode
DEBUG=rsbuild pnpm dev
# Debug production mode
DEBUG=rsbuild pnpm build

Then open the generated rspack.config.web.mjs file and search for the babel-loader keyword to see the complete babel-loader configuration.
#FAQ
#Compilation freezes
After using the babel plugin, if the compilation progress bar is stuck, but there is no Error log on the terminal, it is usually because an exception occurred during the compilation. In some cases, when Error is caught by webpack or other modules, the error log cannot be output correctly. The most common scenario is that there is an exception in the Babel config, which is caught by webpack, and webpack swallows the Error in some cases.
Solution:
If this problem occurs after you modify the Babel config, it is recommended to check for the following incorrect usages:
You have configured a plugin or preset that does not exist, maybe the name is misspelled, or it is not installed correctly.
// wrong example
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    // The plugin has the wrong name or is not installed
    addPlugins('babel-plugin-not-exists');
Whether multiple babel-plugin-imports are configured, but the name of each babel-plugin-import is not declared in the third item of the array.
// wrong example
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    addPlugins([
      ['babel-plugin-import', { libraryName: 'antd', libraryDirectory: 'es' }],
        'babel-plugin-import',
        { libraryName: 'antd-mobile', libraryDirectory: 'es' },
// correct example
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    addPlugins([
        'babel-plugin-import',
        { libraryName: 'antd', libraryDirectory: 'es' },
        'antd',
        'babel-plugin-import',
        { libraryName: 'antd-mobile', libraryDirectory: 'es' },
        'antd-mobile',