rspack-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rspack Best Practices

Rspack 最佳实践

Apply these rules when writing or reviewing Rspack projects.

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

Configuration

配置

Use
```
rspack.config.ts
```
and
```
defineConfig
```
Define explicit
```
entry
```
values for multi-page applications
Keep one main config and branch by
```
process.env.NODE_ENV
```
only when needed
Keep rule conditions narrow and explicit (
```
test
```
,
```
include
```
,
```
exclude
```
,
```
resourceQuery
```
)
Prefer built-in Rspack plugins/loaders over community JS alternatives when equivalent features exist

使用
```
rspack.config.ts
```
和
```
defineConfig
```
为多页面应用定义明确的
```
entry
```
值
仅在必要时保留一个主配置，并根据
```
process.env.NODE_ENV
```
进行分支处理
保持规则条件精准且明确（
```
test
```
、
```
include
```
、
```
exclude
```
、
```
resourceQuery
```
）
当存在等效功能时，优先使用Rspack内置的插件/加载器，而非社区JavaScript替代方案

CLI

CLI 命令

@rspack/cli

is installed:

Use
```
rspack dev
```
for local development
Use
```
rspack build
```
for production build
Use
```
rspack preview
```
only for local production preview

如果已安装

@rspack/cli

：

使用
```
rspack dev
```
进行本地开发
使用
```
rspack build
```
进行生产环境构建
仅使用
```
rspack preview
```
进行本地生产环境预览

Type checking

类型检查

Use
```
ts-checker-rspack-plugin
```
for integrated dev/build type checks
Or run
```
tsc --noEmit
```
/
```
vue-tsc --noEmit
```
as an explicit script step

使用
```
ts-checker-rspack-plugin
```
实现开发/构建过程中的集成式类型检查
或者将
```
tsc --noEmit
```
/
```
vue-tsc --noEmit
```
作为显式的脚本步骤执行

CSS

CSS 处理

Choose one strategy:

Built-in CSS (
```
type: 'css' | 'css/auto' | 'css/module'
```
) for modern setups
```
css-loader
```
+
```
CssExtractRspackPlugin
```
for webpack migration compatibility
```
style-loader
```
for pure style-in-JS runtime injection scenarios

Optional:

Use
```
builtin:lightningcss-loader
```
when goals are syntax downgrade + vendor prefixing
Use
```
sass-loader
```
/
```
less-loader
```
for preprocessing Sass/Less files
Use
```
@tailwindcss/webpack
```
for Tailwind CSS integration

选择以下一种策略：

现代化项目使用内置CSS功能（
```
type: 'css' | 'css/auto' | 'css/module'
```
）
迁移webpack项目时使用
```
css-loader
```
+
```
CssExtractRspackPlugin
```
以保证兼容性
纯JS运行时注入样式的场景使用
```
style-loader
```

可选配置：

当需要语法降级和浏览器厂商前缀时，使用
```
builtin:lightningcss-loader
```
预处理Sass/Less文件时使用
```
sass-loader
```
/
```
less-loader
```
集成Tailwind CSS时使用
```
@tailwindcss/webpack
```

Bundle size optimization

包体积优化

Prefer dynamic
```
import()
```
for non-critical code paths
Prefer lightweight libraries where possible
Keep
```
target
```
aligned with real compatibility requirements

对非关键代码路径优先使用动态
```
import()
```
尽可能使用轻量级库
使
```
target
```
与实际兼容性需求保持一致

Asset management

资源管理

Import source-managed assets from project source directories, not from
```
public
```
Reference
```
public
```
files by absolute URL path

Prefer asset modules (

asset

asset/resource

asset/inline

asset/source

) over legacy

file-loader

url-loader

raw-loader

从项目源码目录导入受源码管理的资源，而非从
```
public
```
目录导入
使用绝对URL路径引用
```
public
```
目录下的文件

优先使用资源模块（

asset

、

asset/resource

、

asset/inline

、

asset/source

），而非传统的

file-loader

url-loader

raw-loader

Profiling

性能分析

Use Node CPU profiling (
```
--cpu-prof
```
) when JavaScript-side overhead is suspected
Use
```
RSPACK_PROFILE=OVERVIEW
```
and analyze trace output for compiler-phase bottlenecks
Replace known slow stacks first (
```
babel-loader
```
, PostCSS, terser) with Rspack built-ins when feasible

当怀疑存在JavaScript层面的性能开销时，使用Node CPU分析（
```
--cpu-prof
```
）
使用
```
RSPACK_PROFILE=OVERVIEW
```
并分析追踪输出，以定位编译阶段的性能瓶颈
在可行的情况下，优先使用Rspack内置功能替代已知的慢处理栈（
```
babel-loader
```
、PostCSS、terser）

Security

安全规范

Do not publish
```
.map
```
files to public servers/CDNs when production source maps are enabled

当启用生产环境source map时，请勿将
```
.map
```
文件发布到公共服务器/CDN

Documentation

文档参考

For the latest (v2) docs, read http://rspack.rs/llms.txt
For Rspack v1 docs, read http://v1.rspack.rs/llms.txt

最新（v2版本）文档请参考：http://rspack.rs/llms.txt
Rspack v1版本文档请参考：http://v1.rspack.rs/llms.txt