Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: translate Rsbuild configurations #543

Merged
merged 3 commits into from
Dec 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions website/docs/en/config/rsbuild/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ To learn more about Rslib configurations, check out [Configure Rslib](/guide/bas

## Overview

- [source](/config/rsbuild/source): Configure the source code parsing and compilation options.
- [output](/config/rsbuild/output): Configure the build outputs.
- [tools](/config/rsbuild/tools): Configure the low-level tools.
- [resolve](/config/rsbuild/resolve): Options for module resolution.
- [source](/config/rsbuild/source): Options for input source code.
- [output](/config/rsbuild/output): Options for build outputs.
- [tools](/config/rsbuild/tools): Options for low-level tools.
- [plugins](/config/rsbuild/plugins): Configure Rsbuild plugins.
2 changes: 1 addition & 1 deletion website/docs/en/config/rsbuild/output.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# output

Configure the build outputs.
Options for build outputs.

{/* ## output.assetPrefix <RsbuildDocBadge path="/config/output/asset-prefix" text="output.assetPrefix" /> */}

Expand Down
12 changes: 9 additions & 3 deletions website/docs/en/config/rsbuild/resolve.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# resolve

Options for module resolution.

## resolve.aliasStrategy <RsbuildDocBadge path="/config/resolve/alias-strategy" text="resolve.aliasStrategy" />

`resolve.aliasStrategy` is used to control the priority between the `paths` option in `tsconfig.json` and the `alias` option in the bundler.
Control the priority between the `paths` option in `tsconfig.json` and the `resolve.alias` option of Rsbuild.

## resolve.alias <RsbuildDocBadge path="/config/resolve/alias" text="resolve.alias" />

Expand All @@ -14,7 +16,7 @@ It is important to note that `resolve.alias` differs from [output.externals](/co

- `resolve.alias` allows you to replace the target module you want to include in the output bundles with another module. It only works if [lib.bundle](/config/lib/bundle) is set to `true`.

For example, if you want to replace `lodash` with `lodash-es` in a bundled CLI application, you can configure it as follows:
For example, if you want to replace `lodash` with `lodash-es` when bundling a package, you can configure it as follows:

```ts title="rslib.config.ts"
export default {
Expand Down Expand Up @@ -49,4 +51,8 @@ It is important to note that `resolve.alias` differs from [output.externals](/co

## resolve.dedupe <RsbuildDocBadge path="/config/resolve/dedupe" text="resolve.dedupe" />

`resolve.dedupe` is used to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.
Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.

## resolve.extensions <RsbuildDocBadge path="/config/resolve/extensions" text="resolve.extensions" />

Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.
6 changes: 3 additions & 3 deletions website/docs/en/config/rsbuild/source.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# source

Configure the source code parsing and compilation options.
Options for input source code.

## source.assetsInclude <RsbuildDocBadge path="/config/source/assets-include" text="source.include" />

Expand All @@ -27,11 +27,11 @@ Check out the [lib.bundle](/config/lib/bundle#set-entry) to learn how to set ent

## source.exclude <RsbuildDocBadge path="/config/source/exclude" text="source.exclude" />

Specifies JavaScript/TypeScript files that do not need to be compiled. The usage is consistent with [Rule.exclude](https://rspack.dev/config/module#ruleexclude) in Rspack, which supports passing in strings or regular expressions to match the module path.
Specifies JavaScript/TypeScript files that do not need to be compiled.

## source.include <RsbuildDocBadge path="/config/source/include" text="source.include" />

The `source.include` is used to specify additional JavaScript files that need to be compiled.
Specify additional JavaScript files that need to be compiled.

{/* ## source.preEntry <RsbuildDocBadge path="/config/source/pre-entry" text="source.preEntry" /> */}

Expand Down
6 changes: 3 additions & 3 deletions website/docs/en/config/rsbuild/tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# tools

Configure the low-level tools.
Options for low-level tools.

## tools.bundlerChain <RsbuildDocBadge path="/config/tools/bundler-chain" text="tools.bundlerChain" />

[rspack-chain](https://github.com/rspack-contrib/rspack-chain) is a utility library for configuring Rspack.
[rspack-chain](https://github.com/rspack-contrib/rspack-chain) is a utility library for configuring Rspack. By using `rspack-chain`, you can more easily modify and extend Rspack configurations.

{/* ## tools.cssExtract <RsbuildDocBadge path="/config/tools/css-extract" text="tools.cssExtract" /> */}

Expand All @@ -30,7 +30,7 @@ Rsbuild integrates PostCSS by default, you can configure [postcss-loader](https:

## tools.rspack <RsbuildDocBadge path="/config/tools/rspack" text="tools.rspack" />

`tools.rspack` is used to configure [Rspack](https://rspack.dev/).
`tools.rspack` is used to configure [Rspack](https://rspack.dev/config/index).

## tools.styleLoader <RsbuildDocBadge path="/config/tools/style-loader" text="tools.styleLoader" />

Expand Down
16 changes: 16 additions & 0 deletions website/docs/zh/config/rsbuild/index.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,17 @@
import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# Rsbuild 配置

Rslib 继承了 Rsbuild 的配置,所以你也可以配置 <RsbuildDocBadge path="/config" text="config" /> 选项。本章节介绍了一些常见的配置项,并解释了如何在 Rslib 中使用它们。

:::tip
要了解更多关于 Rslib 的配置,请查看 [Configure Rslib](/guide/basic/configure-rslib)。
:::

## 概览

- [resolve](/config/rsbuild/resolve): 与模块解析相关的选项。
- [source](/config/rsbuild/source): 与输入的源代码相关的选项。
- [output](/config/rsbuild/output): 与构建产物相关的选项。
- [tools](/config/rsbuild/tools): 与底层工具相关的选项。
- [plugins](/config/rsbuild/plugins): 配置 Rsbuild 插件。
90 changes: 90 additions & 0 deletions website/docs/zh/config/rsbuild/output.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,91 @@
import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# output

与构建产物相关的选项。

## output.charset <RsbuildDocBadge path="/config/output/charset" text="output.charset" />

指定输出文件的 [字符编码](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding),以确保它们在不同的环境中能够正确显示。

## output.cleanDistPath <RsbuildDocBadge path="/config/output/clean-dist-path" text="output.cleanDistPath" />

是否在构建开始前清理产物目录下的所有文件(产物目录默认为 `dist`)。

## output.copy <RsbuildDocBadge path="/config/output/copy" text="output.copy" />

将指定的文件或目录拷贝到构建输出目录中,基于 [rspack.CopyRspackPlugin](https://rspack.dev/zh/plugins/rspack/copy-rspack-plugin) 实现。

## output.cssModules <RsbuildDocBadge path="/config/output/css-modules" text="output.cssModules" />

用于自定义 CSS Modules 配置。

## output.dataUriLimit <RsbuildDocBadge path="/config/output/data-uri-limit" text="output.dataUriLimit" />

设置图片、字体、媒体等静态资源被自动内联为 base64 的体积阈值。

## output.distPath <RsbuildDocBadge path="/config/output/dist-path" text="output.distPath" />

设置构建产物的输出目录,Rsbuild 会根据产物的类型输出到对应的子目录下。

## output.emitCss <RsbuildDocBadge path="/config/output/emit-css" text="output.emitCss" />

是否将 CSS 输出到产物中。

## output.externals <RsbuildDocBadge path="/config/output/externals" text="output.externals" />

在构建时,防止将代码中某些 `import` 的依赖包打包到 bundle 中,而是在运行时再去从外部获取这些依赖。

需要注意的是,`output.externals` 与 [resolve.alias](/config/rsbuild/resolve#resolvealias) 有所不同。请查看 [resolve.alias](/config/rsbuild/resolve#resolvealias) 文档以了解更多信息。

## output.filenameHash <RsbuildDocBadge path="/config/output/filename-hash" text="output.filenameHash" />

在生产模式构建后,是否在产物的文件名中添加 hash 值。

## output.filename <RsbuildDocBadge path="/config/output/filename" text="output.filename" />

设置构建产物的名称。

## output.inlineScripts <RsbuildDocBadge path="/config/output/inline-scripts" text="output.inlineScripts" />

用来控制是否用 `<script>` 标签将产物中的 script 文件(.js 文件)inline 到 HTML 中。

## output.inlineStyles <RsbuildDocBadge path="/config/output/inline-styles" text="output.inlineStyles" />

用来控制是否用 `<style>` 标签将产物中的 style 文件(.css 文件)inline 到 HTML 中。

## output.legalComments <RsbuildDocBadge path="/config/output/legal-comments" text="output.legalComments" />

配置 legal comment 的处理方式。

## output.manifest <RsbuildDocBadge path="/config/output/manifest" text="output.manifest" />

是否生成 manifest 文件,该文件包含所有构建产物的信息、以及[入口模块](https://rsbuild.dev/zh/config/source/entry)与构建产物间的映射关系。

## output.minify <RsbuildDocBadge path="/config/output/minify" text="output.minify" />

用于设置是否在生产模式下开启代码压缩,或是配置压缩工具的选项。

## output.overrideBrowserslist <RsbuildDocBadge path="/config/output/override-browserslist" text="output.overrideBrowserslist" />

指定项目兼容的目标浏览器范围。

## output.polyfill <RsbuildDocBadge path="/config/output/polyfill" text="output.polyfill" />

控制 polyfills 的注入方式。

:::warning
Rsbuild 的 `output.polyfill` 会将 polyfills 注入到全局作用域中,这可能会意外地修改库消费者的全局变量。对于非全局的 polyfill 方案,请参考 [Polyfill - 浏览器](/guide/advanced/output-compatibility#浏览器)。
:::

## output.sourceMap <RsbuildDocBadge path="/config/output/source-map" text="output.sourceMap" />

用于设置是否生成 source map 文件,以及生成哪一种格式的 source map。

## output.target <RsbuildDocBadge path="/config/output/target" text="output.target" />

用于设置 Rsbuild 的构建产物类型。

:::info
请查看 [解决方案](/guide/solution/) 了解更多关于构建产物的信息。
:::
57 changes: 57 additions & 0 deletions website/docs/zh/config/rsbuild/resolve.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,58 @@
import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# resolve

与模块解析相关的选项。

## resolve.aliasStrategy <RsbuildDocBadge path="/config/resolve/alias-strategy" text="resolve.aliasStrategy" />

控制 `tsconfig.json` 中的 `paths` 选项与 Rsbuild 中的 `resolve.alias` 选项的优先级。

## resolve.alias <RsbuildDocBadge path="/config/resolve/alias" text="resolve.alias" />

设置文件引用的别名,对应 Rspack 的 [resolve.alias](https://rspack.dev/zh/config/resolve#resolvealias) 配置。

值得注意的是,`resolve.alias` 与 [output.externals](/config/rsbuild/output#outputexternals) 在以下方面有所不同:

- `resolve.alias` 允许你将目标模块替换为另一个模块。它仅在 [lib.bundle](/config/lib/bundle) 设置为 `true` 时有效。

例如,如果你想在打包一个 package 时将 `lodash` 替换为 `lodash-es`,可以这样配置:

```ts title="rslib.config.ts"
export default {
// ...
resolve: {
alias: {
lodash: 'lodash-es',
},
},
};
```

所有在源代码中导入的 `lodash` 模块将被映射为 `lodash-es`,并被打包到产物中。

- `output.externals` 用于处理外部化模块的别名映射。外部化模块不会被打包到产物中,而是在运行时从外部源导入。

例如,如果你想在 bundle 中将 `react` 和 `react-dom` 替换为 `preact/compat`,可以这样配置:

```ts title="rslib.config.ts"
export default {
// ...
output: {
externals: {
react: 'preact/compat',
'react-dom': 'preact/compat',
},
},
};
```

此时,代码 `import { useState } from 'react'` 将被替换为 `import { useState } from 'preact/compat'`。

## resolve.dedupe <RsbuildDocBadge path="/config/resolve/dedupe" text="resolve.dedupe" />

强制 Rsbuild 从项目根目录解析指定的包,这可以用于移除重复包和减少包大小。

## resolve.extensions <RsbuildDocBadge path="/config/resolve/extensions" text="resolve.extensions" />

自动添加导入文件的扩展名。这意味着你可以导入文件,而不需要显式地写它们的扩展名。
40 changes: 40 additions & 0 deletions website/docs/zh/config/rsbuild/source.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,41 @@
import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# source

与输入的源代码相关的选项。

## source.assetsInclude <RsbuildDocBadge path="/config/source/assets-include" text="source.include" />

指定需要被视为静态资源的额外文件类型。

## source.decorators <RsbuildDocBadge path="/config/source/decorators" text="source.decorators" />

用于配置装饰器语法。

## source.define <RsbuildDocBadge path="/config/source/define" text="source.define" />

构建时将代码中的变量替换成其它值或者表达式,可以用于在代码逻辑中区分开发模式与生产模式等场景。

## source.entry <RsbuildDocBadge path="/config/source/entry" text="source.entry" />

用于设置构建的入口模块。

:::info
参考 [lib.bundle](/config/lib/bundle#set-entry) 了解如何为 bundle 和 bundleless 项目设置入口。
:::

## source.exclude <RsbuildDocBadge path="/config/source/exclude" text="source.exclude" />

指定不需要编译的 JavaScript/TypeScript 文件。

## source.include <RsbuildDocBadge path="/config/source/include" text="source.include" />

指定额外需要编译的 JavaScript 文件。

## source.transformImport <RsbuildDocBadge path="/config/source/transform-import" text="source.transformImport" />

转换 import 的路径,可以用于模块化引用三方包的子路径,能力类似于 [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)。

## source.tsconfigPath <RsbuildDocBadge path="/config/source/tsconfig-path" text="source.tsconfigPath" />

配置自定义的 tsconfig.json 文件路径,可以是相对路径或绝对路径。
32 changes: 32 additions & 0 deletions website/docs/zh/config/rsbuild/tools.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,33 @@
import { RsbuildDocBadge } from '@components/RsbuildDocBadge';

# tools

与底层工具相关的选项。

## tools.bundlerChain <RsbuildDocBadge path="/config/tools/bundler-chain" text="tools.bundlerChain" />

[rspack-chain](https://github.com/rspack-contrib/rspack-chain) 是一个用于配置 Rspack 的工具库,通过 `tools.bundlerChain` 可以调用 `rspack-chain` 以修改默认的 Rspack 配置。

## tools.cssLoader <RsbuildDocBadge path="/config/tools/css-loader" text="tools.cssLoader" />

Rsbuild 默认使用 [css-loader](https://github.com/webpack-contrib/css-loader) 来处理 CSS 资源。你可以通过 `tools.cssLoader` 来修改 css-loader 的选项。

## tools.lightningcssLoader <RsbuildDocBadge path="/config/tools/lightningcss-loader" text="tools.lightningcssLoader" />

通过 `tools.lightningcssLoader` 可以设置 [builtin:lightningcss-loader](https://rspack.dev/zh/guide/features/builtin-lightningcss-loader) 的选项。

## tools.postcss <RsbuildDocBadge path="/config/tools/postcss" text="tools.postcss" />

Rsbuild 默认集成 PostCSS,你可以通过 `tools.postcss` 对 [postcss-loader](https://github.com/webpack-contrib/postcss-loader) 进行配置。

## tools.rspack <RsbuildDocBadge path="/config/tools/rspack" text="tools.rspack" />

`tools.rspack` 选项用于修改 [Rspack](https://rspack.dev/zh/config/index) 的配置项。

## tools.styleLoader <RsbuildDocBadge path="/config/tools/style-loader" text="tools.styleLoader" />

通过 `tools.styleLoader` 可以设置 [style-loader](https://github.com/webpack-contrib/style-loader) 的配置项。

## tools.swc <RsbuildDocBadge path="/config/tools/swc" text="tools.swc" />

通过 `tools.swc` 可以设置 [builtin:swc-loader](https://rspack.dev/zh/guide/features/builtin-swc-loader) 的选项。
Loading