rstackjs/rspack-best-practices

Rspack Best Practices

Apply these rules when writing or reviewing Rspack projects.

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

CLI

If @rspack/cli is installed:

• Use rspack dev for local development
• Use rspack build for production build
• Use rspack preview only for local production 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

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

Bundle size optimization

• Prefer dynamic import() for non-critical code paths
• Prefer lightweight libraries where possible
• Keep target 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
• Prefer asset modules (asset, asset/resource, asset/inline, asset/source) over legacy 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

Security

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

Documentation

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