close
  • 简体中文

      • 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 版本），你可以通过以下配置来按需引入组件：

      rsbuild.config.ts
      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 来自动引用子路径，减小包体积。

      rsbuild.config.ts
      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 配置中。

      rsbuild.config.ts
      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'。

      rsbuild.config.ts
      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 配置，并对其进行修改。

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

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

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