rstackjs/rsbuild-best-practices

Rsbuild Best Practices

Apply these rules when writing or reviewing Rsbuild projects.

Configuration

• Use rsbuild.config.ts and defineConfig
• Use tools.rspack or tools.bundlerChain only when no first-class Rsbuild option exists
• Define explicit source.entry values for multi-page applications
• In TypeScript projects, prefer tsconfig.json path aliases first

CLI

• Use rsbuild for local development
• Use rsbuild build for production build
• Use rsbuild preview only for local production preview
• Use rsbuild inspect to inspect final Rsbuild/Rspack configs

Type checking

• Use @rsbuild/plugin-type-check for integrated dev/build type checks
• Or run tsc --noEmit/vue-tsc --noEmit as an explicit script step

Bundle size optimization

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

Asset management

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

Security

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

Debugging

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

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

Documentation

• For the latest (v2) docs, read http://rsbuild.rs/llms.txt
• For Rsbuild v1 docs, read http://v1.rsbuild.rs/llms.txt