Back to Details

rslib-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rslib Best Practices

Rslib 最佳实践

Apply these rules when writing or reviewing Rslib library projects.

在编写或评审 Rslib 库项目时请遵循以下规则。

Configuration

配置

Use
```
rslib.config.ts
```
and
```
defineConfig
```
Check Rslib-specific configurations first (e.g.,
```
lib.*
```
), and also leverage Rsbuild configurations (e.g.,
```
source.*
```
,
```
output.*
```
,
```
tools.*
```
) as needed
For deep-level or advanced configuration needs, use
```
tools.rspack
```
or
```
tools.bundlerChain
```
to access Rspack's native configurations
In TypeScript projects, prefer
```
tsconfig.json
```
path aliases

使用
```
rslib.config.ts
```
和
```
defineConfig
```
优先检查 Rslib 专属配置（例如
```
lib.*
```
），也可根据需要使用 Rsbuild 配置（例如
```
source.*
```
、
```
output.*
```
、
```
tools.*
```
）
如需深度或高级配置，可使用
```
tools.rspack
```
或
```
tools.bundlerChain
```
访问 Rspack 原生配置
在 TypeScript 项目中，优先使用
```
tsconfig.json
```
的路径别名

CLI

CLI

Use
```
rslib build
```
to build
Use
```
rslib build --watch
```
to build in watch mode for local development
Use
```
rslib inspect
```
to inspect final Rslib/Rsbuild/Rspack configs

使用
```
rslib build
```
执行构建
本地开发时使用
```
rslib build --watch
```
以监听模式构建
使用
```
rslib inspect
```
查看最终的 Rslib/Rsbuild/Rspack 配置

Output

输出

Prefer to build pure-ESM package with
```
"type": "module"
```
in
```
package.json
```
Prefer to use bundleless mode with
```
output.target
```
set to
```
'web'
```
when building component libraries
Prefer to use bundle mode when building Node.js utility libraries
Ensure
```
exports
```
field in
```
package.json
```
is correctly configured and matches the actual JavaScript output and declaration files output of different formats (ESM, CJS, etc.)

优先构建纯 ESM 包，在
```
package.json
```
中设置
```
"type": "module"
```
构建组件库时，优先使用无打包模式，将
```
output.target
```
设置为
```
'web'
```
构建 Node.js 工具库时，优先使用打包模式
确保正确配置
```
package.json
```
中的
```
exports
```
字段，匹配不同格式（ESM、CJS 等）的实际 JavaScript 输出和声明文件输出

Declaration files

声明文件

Prefer to enable declaration file generation with
```
lib.dts: true
```
or detailed configurations
For faster type generation, enable
```
lib.dts.tsgo
```
experimental feature with
```
@typescript/native-preview
```
installed

优先通过
```
lib.dts: true
```
或详细配置开启声明文件生成
如需更快的类型生成速度，可安装
```
@typescript/native-preview
```
后开启
```
lib.dts.tsgo
```
实验性功能

Dependencies

依赖

Prefer to place dependencies to be bundled in
```
devDependencies
```
in bundle mode and dependencies in
```
dependencies
```
and
```
peerDependencies
```
will be automatically externalized (not bundled) by default
Verify the build output and dependency specifiers in
```
package.json
```
carefully to ensure no missing dependency errors occur when consumers install and use this package

打包模式下，优先将需要被打包的依赖放在
```
devDependencies
```
中，默认情况下
```
dependencies
```
和
```
peerDependencies
```
中的依赖会被自动外置（不被打包）
仔细校验构建输出和
```
package.json
```
中的依赖声明，确保使用者安装和使用本包时不会出现缺失依赖的错误

Build optimization

构建优化

Keep syntax target in
```
lib.syntax
```
aligned with real compatibility requirements to enable better optimizations
Avoid format-specific APIs in source code for better compatibility with different output formats
Prefer lightweight dependencies to reduce bundle size

保持
```
lib.syntax
```
中的语法目标与实际兼容性要求一致，以获得更好的优化效果
源代码中避免使用特定格式的 API，以便更好地兼容不同的输出格式
优先使用轻量级依赖以减少打包体积

Toolchain integration

工具链集成

Prefer to use Rstest with
```
@rstest/adapter-rslib
```
for writing tests
Prefer to use Rspress for writing library documentation, with
```
@rspress/plugin-preview
```
and
```
@rspress/plugin-api-docgen
```
for component previews and API docs

优先搭配
```
@rstest/adapter-rslib
```
使用 Rstest 编写测试
优先使用 Rspress 编写库文档，搭配
```
@rspress/plugin-preview
```
和
```
@rspress/plugin-api-docgen
```
实现组件预览和 API 文档生成

Debugging

调试

Run with
```
DEBUG=rsbuild
```
when diagnosing config resolution or plugin behavior
Read generated files in
```
dist/.rsbuild
```
to confirm final Rsbuild/Rspack config, not assumed config

排查配置解析或插件行为问题时，添加
```
DEBUG=rsbuild
```
运行命令
查看
```
dist/.rsbuild
```
下生成的文件确认最终的 Rsbuild/Rspack 配置，而非假设的配置

Documentation

文档

For the latest Rslib docs, read https://rslib.rs/llms.txt

查看最新 Rslib 文档请访问：https://rslib.rs/llms.txt