close
Guide
Config
Plugin
API
Community
Version
Guide
Config
Plugin
API
Community

tools.rspack

  • Type: Rspack.Configuration | Function | undefined
  • Default: undefined

tools.rspack configures Rspack.

TIP

The built-in Rspack config in Rsbuild may change with iterations, and these changes will not be reflected in semver. Therefore, your custom config may become invalid when you upgrade Rsbuild.

Object type

tools.rspack accepts an object that gets deep merged with the built-in Rspack configuration through webpack-merge.

For example, add resolve.alias configuration:

rsbuild.config.ts
export default {
  tools: {
    rspack: {
      resolve: {
        alias: {
          '@util': 'src/util',
        },
      },
    },
  },
};

When merging configurations, webpack-merge will automatically concatenate arrays such as plugins, module.rules, resolve.extensions, etc.

rsbuild.config.ts
export default {
  tools: {
    rspack: {
      resolve: {
        // merged with the built-in resolve.extensions
        extensions: ['.foo'],
      },
    },
  },
};

If you need to override a configuration rather than merge it with the default value, you can use the function type of tools.rspack.

Function type

tools.rspack can be configured as a function. The first parameter of this function is the built-in Rspack configuration object, you can modify this object, and then return it. For example:

rsbuild.config.ts
export default {
  tools: {
    rspack: (config) => {
      config.resolve.alias ||= {};
      config.resolve.alias['@util'] = 'src/util';
      return config;
    },
  },
};
TIP

The object returned by the tools.rspack function is used directly as the final Rspack configuration and is not merged with the built-in Rspack configuration.

tools.rspack can also be an async function:

rsbuild.config.ts
export default {
  tools: {
    rspack: async (config) => {
      const { default: ESLintPlugin } = await import('eslint-webpack-plugin');
      config.plugins.push(new ESLintPlugin());
      return config;
    },
  },
};

Utils

The second parameter of this function is an object, which contains some utility functions and properties, as follows:

env

  • Type: 'development' | 'production' | 'test'

The env parameter determines whether the current environment is development, production or test. For example:

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { env }) => {
      if (env === 'development') {
        config.devtool = 'cheap-module-eval-source-map';
      }
      return config;
    },
  },
};

isDev

  • Type: boolean

A boolean value indicating whether this is a development build. Set to true when the mode is development.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { isDev }) => {
      if (isDev) {
        config.devtool = 'eval-cheap-source-map';
      }
      return config;
    },
  },
};

isProd

  • Type: boolean

A boolean value indicating whether this is a production build. Set to true when the mode is production.

rsbuild.config.ts
export default {
  tools: {
    rspack: (chain, { isProd }) => {
      if (isProd) {
        chain.devtool('source-map');
      }
    },
  },
};

target

  • Type: 'web' | 'node' | 'web-worker'

The current build target.

You can set different Rspack configurations for different build targets, for example:

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { target }) => {
      if (target === 'node') {
        // ...
        config.plugins.push(new SomePluginForNode());
        return config;
      }
      return config;
    },
  },
};

isServer

  • Type: boolean

A boolean value indicating whether the build target is node, equivalent to target === 'node'.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { isServer }) => {
      if (isServer) {
        // ...
      }
      return config;
    },
  },
};

isWebWorker

  • Type: boolean

A boolean value indicating whether the build target is web-worker, equivalent to target === 'web-worker'.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { isWebWorker }) => {
      if (isWebWorker) {
        // ...
      }
      return config;
    },
  },
};

rspack

  • Type: Rspack

The Rspack instance, the same as import { rspack } from '@rsbuild/core'.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { rspack }) => {
      config.plugins.push(new rspack.BannerPlugin());
      return config;
    },
  },
};

environment

Context information about the current environment.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { environment }) => {
      console.log(environment);
    },
  },
};

HtmlPlugin

  • Type: typeof import('html-rspack-plugin')

The default export of html-rspack-plugin.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { HtmlPlugin }) => {
      console.log(HtmlPlugin);
    },
  },
};

addRules

  • Type: (rules: RuleSetRule | RuleSetRule[]) => void

Add additional Rspack rules to the head of the internal Rspack module rules array.

It should be noted that Rspack loaders will be executed in right-to-left order. If you want the loader you added to be executed before other loaders (Normal Phase), you should use appendRules to add the rule to the end.

For example:

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { addRules }) => {
      // add a single rule
      addRules({
        test: /\.foo/,
        loader: require.resolve('foo-loader'),
      });

      // Add multiple rules as an array
      addRules([
        {
          test: /\.foo/,
          loader: require.resolve('foo-loader'),
        },
        {
          test: /\.bar/,
          loader: require.resolve('bar-loader'),
        },
      ]);
    },
  },
};

appendRules

  • Type: (rules: RuleSetRule | RuleSetRule[]) => void

Add additional Rspack rules to the end of the internal Rspack module rules array.

For example:

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { appendRules }) => {
      // add a single rule
      appendRules({
        test: /\.foo/,
        loader: require.resolve('foo-loader'),
      });

      // Add multiple rules as an array
      appendRules([
        {
          test: /\.foo/,
          loader: require.resolve('foo-loader'),
        },
        {
          test: /\.bar/,
          loader: require.resolve('bar-loader'),
        },
      ]);
    },
  },
};

prependPlugins

  • Type: (plugins: BundlerPluginInstance | BundlerPluginInstance[]) => void

Add additional plugins to the head of the internal Rspack plugins array, and the plugin will be executed first.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { prependPlugins }) => {
      // add a single plugin
      prependPlugins(new PluginA());

      // Add multiple plugins
      prependPlugins([new PluginA(), new PluginB()]);
    },
  },
};

appendPlugins

  • Type: (plugins: BundlerPluginInstance | BundlerPluginInstance[]) => void

Add additional plugins at the end of the internal Rspack plugins array, the plugin will be executed last.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { appendPlugins }) => {
      // add a single plugin
      appendPlugins([new PluginA()]);

      // Add multiple plugins
      appendPlugins([new PluginA(), new PluginB()]);
    },
  },
};

removePlugin

  • Type: (name: string) => void

Remove the internal Rspack plugin, the parameter is the constructor.name of the plugin.

For example, remove the internal webpack-bundle-analyzer:

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { removePlugin }) => {
      removePlugin('BundleAnalyzerPlugin');
    },
  },
};

mergeConfig

  • Type: (...configs:Rspack.Configuration[]) =>Rspack.Configuration

Used to merge multiple Rspack configs, the same as webpack-merge.

rsbuild.config.ts
export default {
  tools: {
    rspack: (config, { mergeConfig }) => {
      return mergeConfig(config, {
        devtool: 'eval',
      });
    },
  },
};
TIP

The mergeConfig method will create a new config object without modifying the original config object, so you need to return the result of mergeConfig.