Builtins#

Used to set the built-in functions provided by Rspack.

• Type: Record<string, any>
• Default: {}

builtins.banner#

• Type:

type BannerCondition = string | RegExp | Array<string | RegExp>;

type BannerConfig =
  | string
  | {
      banner: string;
      entryOnly?: boolean;
      footer?: boolean;
      raw?: boolean;
      test?: BannerCondition;
      include?: BannerCondition;
      exclude?: BannerCondition;
    };

export type BannerConfigs = BannerConfig | BannerConfig[];

• Default: undefined

Adds a banner to the top or bottom of each generated chunk.

module.exports = {
  builtins: {
    banner: [
      {
        banner: 'hello world',
        footer: true,
      },
    ],
  },
};

builtins.emotion#

Using optimization for emotion in compile-time.

• Type:

type EmotionOptions =
  | boolean
  | {
      sourceMap?: boolean;
      autoLabel?: 'never' | 'dev-only' | 'always';
      labelFormat?: string;
      importMap?: {
        [packageName: string]: {
          [exportName: string]: {
            canonicalImport?: [string, string];
          };
        };
      };
    };

• Default: false

If you are using emotion in your project, and want functionality which is similar to @emotion/babel-plugin, you can enable builtins.emotion option, Rspack will use swc_emotion plugin to transpile your emotion code.

You can enable default options by specify builtins.emotion: true.

module.exports = {
  context: __dirname,
  entry: {
    main: './src/index.js',
  },
  builtins: {
    emotion: true,
  },
};

Each field name is the same with @emotion/babel-plugin, more detailed explanation (content below is from the official document of @emotion/babel-plugin):

autoLabel#

• Type: 'never' | 'dev-only' | 'always'
• Default: 'dev-only'

This option is used for:

• Automatically adds the label property to styles so that class names generated by css or styled include the name of the variable the result is assigned to.
• Please note that non word characters in the variable will be removed (Eg. iconStyles$1 will become iconStyles1) because $ is not validCSS ClassName Selector.

Each possible value for this option produces different output code:

• 'dev-only' - we optimize the production code, so there are no labels added there, but at the same time we keep labels for development environments,
• 'always' - we always add labels when possible,
• 'never' - we disable this entirely and no labels are added.

labelFormat#

• Type: string
• Default: "[local]"

This option only works when 'autoLabel' is set to 'dev-only' or 'always'. It allows you to define the format of the resulting label. The format is defined via string where variable parts are enclosed in square brackets []. For example labelFormat: "my-classname--[local]", where '[local]' will be replaced with the name of the variable the result is assigned to.

Allowed values:

• '[local]' - the name of the variable the result of the css or styled expression is assigned to.
• '[filename]' - name of the file (without extension) where css or styled expression is located.
• '[dirname]' - name of the directory containing the file where css or styled expression is located.

This format only affects the label property of the expression, meaning that the css prefix and hash will be prepended automatically.

sourceMap#

• Type: boolean

Whether to inject source maps. By default, this will be disabled in production mode, and enabled in development mode.

importMap#

• Type:

export type ImportMap =
  | undefined
  | {
      [packageName: string]: {
        [exportName: string]: {
          canonicalImport?: [string, string];
        };
      };
    };

• Default: undefined

This option allows you to tell Rspack what imports it should look at to determine what it should transform so if you re-export Emotion's exports, you can still use the Babel transforms

builtins.presetEnv#

This option allows your code to run on older versions of browsers by querying all the browsers that need to be supported through browserslist. If the source code uses APIs that are not supported by these browsers, the same APIs can be provided to these browsers by globally injecting core-js. If the source code uses syntax that is not supported by these browsers, the syntax will also be converted into syntax supported by the browsers.

• Type:

type PresetEnv =
  | undefined
  | {
      mode?: 'entry'; // `usage` mode will be supported in the near future
      targets?: string[];
      coreJs?: string;
    };

• Default: undefined

module.exports = {
  resolve: {
    alias: {
      'core-js': require('path').dirname(require.resolve('core-js')),
    },
  },
};

builtins.html#

This configuration simplifies creation of HTML files to serve your Rspack bundles.

• Type:

type BuiltinsHtml = Array<{
  title?: string;
  filename?: string;
  template?: string;
  templateContent?: string;
  templateParameters?: Record<string, string>;
  inject?: 'head' | 'body';
  publicPath?: string;
  scriptLoading?: 'blocking' | 'defer' | 'module';
  chunks?: string[];
  excludedChunks?: string[];
  sri?: 'sha256' | 'sha384' | 'sha512';
  minify?: boolean;
  favicon?: string;
  meta?: Record<string, string | Record<string, string>>;
}>;

• Default: []

builtins.minifyOptions#

Set built-in minimizer options.

• Type:

type BuiltinsMinifyOptions = {
  passes?: number;
  dropConsole?: boolean;
  keepClassNames?: boolean;
  keepFnNames?: boolean;
  pureFuncs?: Array<string>;
  extractComments: boolean | RegExp;
  asciiOnly?: boolean;
  comments?: false | 'all' | 'some';
};

builtins.define#

Replaces variables in your code with other values or expressions at compile time.

• Type: Record<string, string | boolean | undefined>
• Default: {}

When using the following configuration:

module.exports = {
  builtins: {
    define: {
      'process.env.NODE_ENV': "'development'",
      TRUE: true,
      TRUE_STRING: 'true',
      UNDEFINED: undefined,
      UNDEFINED_STRING: 'undefined',
    },
  },
};

Input:

if (process.env.NODE_ENV === 'development') {
  console.log('run in development mode');
}

console.log(TRUE === TRUE_STRING);
console.log(UNDEFINED === UNDEFINED_STRING);

Output:

if ('development' === 'development') {
  console.log('run in development mode');
}

fetch('/api/test');

console.log(true === true);
console.log(undefined === undefined);

builtins.react#

This configuration can control the code transformation about react.

• Type:

type ReactOptions = {
  runtime?: 'automatic' | 'classic';
  importSource?: string;
  pragma?: string;
  pragmaFrag?: string;
  throwIfNamespace?: boolean;
  development?: boolean;
  useBuiltins?: boolean;
  useSpread?: boolean;
  refresh?: boolean;
};

• Default: {}

builtins.decorator#

This configuration can be used to control decorator transform behavior, false means to turn off transform.

• Type:

type BuiltinsDecorator =
  | boolean
  | {
      legacy?: boolean;
      emitMetadata?: boolean;
    };

• Default: true

builtins.css#

This configuration can be used to control how Rspack handles css.

• Type:

type BuiltinsCss = {
  modules?: BuiltinsCssModules;
};

builtins.css.modules#

css modules options.

• Type:

type BuiltinsCssModules = {
  localsConvention?:
    | 'asIs'
    | 'camelCase'
    | 'camelCaseOnly'
    | 'dashes'
    | 'dashesOnly';
  localIdentName?: string;
  exportsOnly?: boolean;
};

builtins.progress#

This configuration can be used to control progress, false means to turn off progress.

• Type: boolean | { prefix?: string }
• Default: production mode isfalse, development mode istrue

builtins.devFriendlySplitChunks#

Whether to enable the development-friendly split chunks algorithm.

• Type: boolean

• Default: false

builtins.copy#

Copies individual files or entire directories, which already exist, to the build directory.

• Type:

export type CopyConfig = {
  patterns: (
    | string // If input is string, it's the same as { from: `your input string` }
    | {
        from: string;
        to?: string; // Determine based on `from`
        context?: string; // Default to `context` in Rspack config
        toType?: 'dir' | 'file' | 'template'; // Determine based on `from`
        noErrorOnMissing?: boolean; // Default to false
        force?: boolean; // Default to false
        priority?: number; // Default to 0
        globOptions?: {
          caseSensitiveMatch?: boolean; // Default to true
          dot?: boolean; // Default to true
          ignore?: string[]; // ignore specific path
        };
      }
  )[];
};

• Default: undefined

For example:

module.exports = {
  entry: './src/index.js',
  builtins: {
    copy: {
      patterns: [
        {
          from: 'file.txt',
        },
      ],
    },
  },
};

The result of running with the above configuration would be: "dist/file.txt".

module.exports = {
  entry: './src/index.js',
  builtins: {
    copy: {
      patterns: [
        {
          from: 'directory',
        },
      ],
    },
  },
};

The result of running with the above configuration would be: files and directories inside directory will be placed at output path.

module.exports = {
  entry: './src/index.js',
  builtins: {
    copy: {
      patterns: [
        {
          from: 'directory/**/*',
          to: 'newdirectory',
        },
      ],
    },
  },
};

The result of running with the above configuration would be that the directory folder is moved to the newdirectory folder within the output folder, for example dist/newdirectory/directory/foo.

builtins.relay#

Converted graphql call expression to corresponding require call expression.

• Type:

export type RelayOptions =
  | undefined
  | boolean
  | {
      artifactDirectory?: string;
      language: 'javascript' | 'typescript' | 'flow'; // Default to 'javascript'
    };

• Default: undefined

When this configuration is set to true, Rspack will attempt to locate relay.config.json, relay.config.js, and package.json files under the context directory in order, as detailed in the relay-compiler documentation. If none of these files are found, Rspack will use the default configuration. If specific configuration is passed, Rspack will not attempt to locate any relay config file, but use the received configuration directly.

builtins.pluginImport#

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:

module.exports = {
  builtins: {
    pluginImport: [
      {
        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:

module.exports = {
  builtins: {
    pluginImport: [
      {
        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 and lowerCase can be used as well.

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:

module.exports = {
  builtins: {
    pluginImport: [
      {
        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:

module.exports = {
  builtins: {
    pluginImport: [
      {
        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';

builtins.provide#

Automatically load modules instead of having to import or require them everywhere.

module.exports = {
  builtins: {
    provide: {
      process: [require.resolve('process/browser')],
    },
  },
};

Which will convert the following code:

console.log(process.version);

To:

import process from 'process/browser';
console.log(process.version);