rslib-best-practices

Rslib 最佳实践

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

配置

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

CLI

• 使用 rslib 进行构建
• 使用 rslib --watch 在本地开发时以监听模式构建
• 使用 rslib inspect 检查最终的 Rslib/Rsbuild/Rspack 配置

输出

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

声明文件

• 优先通过 lib.dts: true 或详细配置启用声明文件生成
• 如需更快地生成类型，请安装 @typescript/native-preview 并启用 lib.dts.tsgo 实验性功能

依赖项

• 在 bundle 模式下，优先将需要打包的依赖项放入 devDependencies；dependencies 和 peerDependencies 中的依赖项默认会自动外置（不打包）
• 仔细检查构建输出和 package.json 中的依赖项说明符，确保使用者安装和使用此包时不会出现依赖项缺失错误

构建优化

• 使 lib.syntax 中的语法目标与实际兼容性要求保持一致，以实现更好的优化
• 避免在源代码中使用特定于格式的 API，以提高对不同输出格式的兼容性
• 优先使用轻量级依赖项，以减小包体积

工具链集成

• 编写测试时，优先将 Rstest 与 @rstest/adapter-rslib 配合使用
• 编写库文档时，优先使用 Rspress，并通过 @rspress/plugin-preview 和 @rspress/plugin-api-docgen 提供组件预览和 API 文档

调试

• 诊断配置解析或插件行为时，使用 DEBUG=rsbuild 运行
• 阅读 dist/.rsbuild 中生成的文件，确认最终的 Rsbuild/Rspack 配置，而不要依赖推测的配置

文档

• 如需查阅最新的 Rslib 文档，请访问 https://rslib.rs/llms.txt