source.transformImport#

• 类型：

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

• 默认值： undefined

转换 import 的路径，可以用于模块化引用三方包的子路径，能力类似于 babel-plugin-import。

示例#

按需引入 antd 组件#

在使用 antd 组件库时（低于 v5 版本），你可以通过以下配置来按需引入组件：

export default {
  source: {
    transformImport: [
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        // 设置 `style: 'css'` 来加载 `.css` 样式
        // 设置 `style: true` 来加载 `.less` 样式
        style: 'css',
      },
    ],
  },
};

源代码如下：

import { Button } from 'antd';

会被转换成：

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

按需引入 lodash#

在使用 lodash 时，你可以通过 transformImport 来自动引用子路径，减小包体积。

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

源代码如下：

import { get } from 'lodash';

会被转换成：

import get from 'lodash/get';

请避免以下用法，否则会引入所有的 lodash 代码：

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

适用范围#

transformImport 只适用于经过 Rsbuild 编译的模块。需要注意的是，Rsbuild 默认并不会编译位于 node_modules 目录下的 JavaScript 文件。这意味着，node_modules 目录内的代码将不会被 transformImport 处理。

如果你希望通过 transformImport 对 node_modules 下的代码进行处理，请将相关模块添加到 source.include 配置中。

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

选项#

libraryName#

• 类型： string

用于指定需要按需加载的模块名称。当 Rsbuild 遍历代码时，如果遇到了对应模块的 import 语句，则会对其进行转换。

libraryDirectory#

• 类型： string
• 默认值： 'lib'

用于拼接转换后的路径，拼接规则为 ${libraryName}/${libraryDirectory}/${member}，其中 member 为引入成员。

示例：

import { Button } from 'foo';

转换结果:

import Button from 'foo/lib/button';

style#

• 类型： boolean
• 默认值： undefined

确定是否需要引入相关样式，若为 true，则会引入路径 ${libraryName}/${libraryDirectory}/${member}/style。若为 false 或 undefined 则不会引入样式。

当配置为 true 时：

import { Button } from 'foo';

转换结果:

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

styleLibraryDirectory#

• 类型： string
• 默认值： undefined

该配置用于拼接引入样式时的引入路径，若该配置被指定，则 style 配置项会被忽略。拼接引入路径为 ${libraryName}/${styleLibraryDirectory}/${member}。

当配置为 styles 时：

import { Button } from 'foo';

转换结果:

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

camelToDashComponentName#

• 类型： boolean
• 默认值： true

是否需要将 camelCase 的引入转换成 kebab-case。

示例：

import { ButtonGroup } from 'foo';

转换结果：

// 设置成 true：
import ButtonGroup from 'foo/button-group';
// 设置成 false：
import ButtonGroup from 'foo/ButtonGroup';

transformToDefaultImport#

• 类型： boolean
• 默认值： true

是否将导入语句转换成默认导入。

示例：

import { Button } from 'foo';

转换结果：

// 设置成 true：
import Button from 'foo/button';
// 设置成 false：
import { Button } from 'foo/button';

customName#

• 类型： string
• 默认值： undefined

自定义转换后的导入路径。

比如下面的配置，会将 import { foo } from 'my-lib' 转换为 import foo from 'my-lib/foo'。

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

此外，你还可以声明转换后的路径格式，例如设置为 my-lib/{{ camelCase member }}，来将 member 转换成驼峰格式。

支持以下格式：

• kebabCase：字母小写，单词之间使用连字符连接。例如：my-variable-name。
• snakeCase：字母小写，单词之间使用下划线连接。例如：my_variable_name。
• camelCase：首字母小写，随后每个单词的首字母大写。例如：myVariableName。
• upperCase：字母大写，其他字符不变。例如：MY-VARIABLE-NAME。
• lowerCase：字母小写，其他字符不变。例如：my-variable-name。

customStyleName#

• 类型： string
• 默认值： undefined

自定义转换后的样式导入路径，用法与 customName 一致。

Function 类型#

transformImport 的值定义为函数时，可以接受原本的 transformImport 配置，并对其进行修改。

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

也可以在函数中返回一个新数组作为最终结果，新数组会覆盖原本的 transformImport 配置。

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