source.transformImport#

• Type:

type TransformImport =
  | Array<{
      libraryName: string;
      libraryDirectory?: string;
      style?: string | boolean;
      styleLibraryDirectory?: string;
      camelToDashComponentName?: boolean;
      transformToDefaultImport?: boolean;
      customName?: string;
      customStyleName?: string;
    }>
  | Function;

• Default: undefined

Transform the import path, which can be used to modularly import the subpath of third-party packages. The functionality is similar to babel-plugin-import.

Example#

Import antd on demand#

When using the antd component library (versions below v5), you can import components on demand with the following config:

export default {
  source: {
    transformImport: [
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: 'css',
      },
    ],
  },
};

The source code is:

import { Button } from 'antd';

Will be transformed into:

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

Import lodash on demand#

When using lodash, you can automatically refer to the subpath through transformImport to reduce bundle size.

export default {
  source: {
    transformImport: [
      {
        libraryName: 'lodash',
        customName: 'lodash/{{ member }}',
      },
    ],
  },
};

The source code is:

import { get } from 'lodash';

Will be transformed to:

import get from 'lodash/get';

Please avoid the following usage, otherwise all of lodash's code will be imported:

import _ from 'lodash';
import lodash from 'lodash';

Scope#

transformImport is only applicable to modules compiled by Rsbuild. Note that Rsbuild does not compile JavaScript files in the node_modules by default. This means that the code in the node_modules directory will not be processed by transformImport.

If you want to process the code in node_modules through transformImport, please add the relevant modules to the source.include config.

export default {
  source: {
    include: [/node_modules[\\/]some-package[\\/]/],
  },
};

Options#

libraryName#

• Type: string

The original import path that needs to be transformed.

libraryDirectory#

• Type: string
• Default: 'lib'

Used to splice the transformed path, the splicing rule is ${libraryName}/${libraryDirectory}/${member}, where member is the imported member.

Example:

import { Button } from 'foo';

Out:

import Button from 'foo/lib/button';

style#

• Type: boolean
• Default: undefined

Determines whether to import related styles. If it is true, the path ${libraryName}/${libraryDirectory}/${member}/style will be imported. If it is false or undefined, the style will not be imported.

When it is set to true:

import { Button } from 'foo';

Out:

import Button from 'foo/lib/button';
import 'foo/lib/button/style';

styleLibraryDirectory#

• Type: string
• Default: undefined

This configuration is used to splice the import path when importing styles. If this configuration is specified, the style configuration option will be ignored. The spliced import path is ${libraryName}/${styleLibraryDirectory}/${member}.

When it is set to styles:

import { Button } from 'foo';

Out:

import Button from 'foo/lib/button';
import 'foo/styles/button';

camelToDashComponentName#

• Type: boolean
• Default: true

Whether to convert camelCase imports to kebab-case.

Example:

import { ButtonGroup } from 'foo';

Out:

// set to true:
import ButtonGroup from 'foo/button-group';
// set to false:
import ButtonGroup from 'foo/ButtonGroup';

transformToDefaultImport#

• Type: boolean
• Default: true

Whether to convert import statements to default imports.

Example:

import { Button } from 'foo';

Out:

// set to true:
import Button from 'foo/button';
// set to false:
import { Button } from 'foo/button';

customName#

• Type: string
• Default: undefined

Customize the transformed path.

For example, the following config will transform import { foo } from 'my-lib' into import foo from 'my-lib/foo'.

export default {
  source: {
    transformImport: [
      {
        libraryName: 'my-lib',
        customName: `my-lib/{{ member }}`,
      },
    ],
  },
};

In addition, you can also declare the format of the path after transformation, such as setting it to my-lib/{{ camelCase member }} to convert member into camel case.

The following formats are supported:

• kebabCase: lowercase letters, words joined by hyphens. For example: my-variable-name.
• snakeCase: lowercase letters, words joined by underscores. For example: my_variable_name.
• camelCase: first letter lowercase, the first letter of each following word uppercase. For example: myVariableName.
• upperCase: uppercase letters, other characters unchanged. For example: MY-VARIABLE-NAME.
• lowerCase: lowercase letters, other characters unchanged. For example: my-variable-name.

customStyleName#

• Type: string
• Default: undefined

Customize the transformed style path, the usage is consistent with customName.

Function Type#

The transformImport can be a function, it will accept the previous value, and you can modify it.

export default {
  source: {
    transformImport: (imports) => {
      return imports.filter((data) => data.libraryName !== 'antd');
    },
  },
};

You can also return a new value as the final result in the function, which will replace the previous value.

export default {
  source: {
    transformImport: () => {
      return [
        {
          libraryName: 'antd',
          libraryDirectory: 'es',
          style: 'css',
        },
      ];
    },
  },
};