close
logologo
指南
配置
插件
API
社区
版本
更新日志
Rsbuild 0.x 文档
English
简体中文
指南
配置
插件
API
社区
更新日志
Rsbuild 0.x 文档
English
简体中文
logologo
Overview
root
mode
plugins
logLevel
environments

dev

dev.assetPrefix
dev.browserLogs
dev.cliShortcuts
dev.client
dev.hmr
dev.lazyCompilation
dev.liveReload
dev.progressBar
dev.setupMiddlewares
dev.watchFiles
dev.writeToDisk

resolve

resolve.aliasStrategy
resolve.alias
resolve.conditionNames
resolve.dedupe
resolve.extensions
resolve.mainFields

source

source.assetsInclude
source.decorators
source.define
source.entry
source.exclude
source.include
source.preEntry
source.transformImport
source.tsconfigPath

output

output.assetPrefix
output.charset
output.cleanDistPath
output.copy
output.cssModules
output.dataUriLimit
output.distPath
output.emitAssets
output.emitCss
output.externals
output.filenameHash
output.filename
output.injectStyles
output.inlineScripts
output.inlineStyles
output.legalComments
output.manifest
output.minify
output.module
output.overrideBrowserslist
output.polyfill
output.sourceMap
output.target

html

html.appIcon
html.crossorigin
html.favicon
html.inject
html.meta
html.mountId
html.outputStructure
html.scriptLoading
html.tags
html.templateParameters
html.template
html.title

server

server.base
server.compress
server.cors
server.headers
server.historyApiFallback
server.host
server.htmlFallback
server.https
server.middlewareMode
server.open
server.port
server.printUrls
server.proxy
server.publicDir
server.strictPort

security

security.nonce
security.sri

tools

tools.bundlerChain
tools.cssExtract
tools.cssLoader
tools.htmlPlugin
tools.lightningcssLoader
tools.postcss
tools.rspack
tools.styleLoader
tools.swc

performance

performance.buildCache
performance.bundleAnalyze
performance.chunkSplit
performance.dnsPrefetch
performance.preconnect
performance.prefetch
performance.preload
performance.printFileSize
performance.profile
performance.removeConsole
performance.removeMomentLocale

moduleFederation

moduleFederation.options
📝 在 GitHub 上编辑此页
上一页source.preEntry
下一页source.tsconfigPath

#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',
        },
      ];
    },
  },
};