tools.babel#

• Type: Object | Function
• Default: undefined

With tools.babel you can modify the options of babel-loader.

Usage Scenarios#

Please note the limitations of tools.babel in the following usage scenarios:

• Rspack scenario: When using Rspack as the bundler, using the tools.babel option will significantly slow down the Rspack's build speed. This is because Rspack defaults to using SWC for compilation, and configuring Babel will cause the code to be compiled twice, resulting in additional compilation overhead.
• webpack + SWC scenario: When using webpack as the bundler, if you use Builder's SWC plugin for code compilation, the tools.babel option will not take effect.

Function Type#

When tools.babel 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.

export default {
  tools: {
    babel(config) {
      // Add a Babel plugin
      // note: the plugin have been added to the default config to support antd load on demand
      config.plugins.push([
        'babel-plugin-import',
        {
          libraryName: 'xxx-components',
          libraryDirectory: 'es',
          style: true,
        },
      ]);
    },
  },
};

The second parameter of the tools.babel function provides some more convenient utility functions. Please continue reading the documentation below.

Object Type#

When tools.babel's type is Object, the config will be shallow merged with default config by Object.assign.

export default {
  tools: {
    babel: {
      plugins: [
        [
          'babel-plugin-import',
          {
            libraryName: 'xxx-components',
            libraryDirectory: 'es',
            style: true,
          },
        ],
      ],
    },
  },
};

Util Functions#

When tools.babel 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:

export default {
  tools: {
    babel(config, { addPlugins }) {
      addPlugins([
        [
          'babel-plugin-import',
          {
            libraryName: 'xxx-components',
            libraryDirectory: 'es',
            style: true,
          },
        ],
      ]);
    },
  },
};

addPresets#

• Type: (presets: BabelPlugin[]) => void

Add Babel preset configuration. (No need to add presets in most cases)

export default {
  tools: {
    babel(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.

export default {
  tools: {
    babel(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.

export default {
  tools: {
    babel(config, { removePresets }) {
      removePresets('@babel/preset-env');
    },
  },
};

modifyPresetEnvOptions#

• Type: (options: PresetEnvOptions) => void

Modify the configuration of @babel/preset-env, the configuration you pass in will be shallowly merged with default config. For example:

export default {
  tools: {
    babel(config, { modifyPresetEnvOptions }) {
      modifyPresetEnvOptions({
        targets: {
          browsers: ['last 2 versions'],
        },
      });
    },
  },
};

modifyPresetReactOptions#

• Type: (options: PresetReactOptions) => void

Modify the configuration of @babel/preset-react, the configuration you pass in will be shallowly merged with default config. For example:

export default {
  tools: {
    babel(config, { modifyPresetReactOptions }) {
      modifyPresetReactOptions({
        pragma: 'React.createElement',
      });
    },
  },
};

addIncludes#

Deprecated, please use source.include instead, both have the same functionality.

addExcludes#

Deprecated, please use source.exclude instead, both have the same functionality.

Debugging Babel Configuration#

After modifying the babel-loader configuration through tools.babel, you can view the final generated configuration in Builder debug mode.

First, enable debug mode by using the DEBUG=builder parameter:

# Debug development mode
DEBUG=builder pnpm dev

# Debug production mode
DEBUG=builder pnpm build

Then open the generated (webpack|rspack).config.web.js file and search for the babel-loader keyword to see the complete babel-loader configuration.