rspack-best-practices

$npx mdskill add rstackjs/agent-skills/rspack-best-practices

Optimize Rspack projects with config, build, and profiling guidance.

  • Enforces explicit entries, narrow rules, and built-in plugins.
  • Integrates with rspack CLI, ts-checker-rspack-plugin, and tsc.
  • Decides recommendations based on project context and goals.
  • Delivers actionable rules for writing, reviewing, and troubleshooting.

SKILL.md

.github/skills/rspack-best-practicesView on GitHub ↗
---
name: rspack-best-practices
description: Rspack best practices for config, CLI workflow, type checking, CSS, bundle optimization, assets and profiling. Use when writing, reviewing, or troubleshooting Rspack projects.
---

# 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

More from rstackjs/agent-skills

SkillDescription
migrate-to-rsbuildMigrate webpack, Vite, create-react-app (CRA/CRACO), or Vue CLI projects to Rsbuild.
migrate-to-rslibMigrate tsc or tsup library projects to Rslib.
migrate-to-rstestMigrate Jest or Vitest test suites and configs to Rstest. Use when asked to move from Jest/Vitest to Rstest, replace framework APIs with `@rstest/core`, translate test config to `rstest.config.ts`, or update test scripts and setup files for Rstest equivalents.
pr-creatorUse when asked to create a pull request for this repository. It helps the PR follow the repository's branch safety rules, title convention, pull request template, and concise English writing style.
rsbuild-best-practicesRsbuild best practices for config, CLI workflow, type checking, bundle optimization, assets, and debugging. Use when writing, reviewing, or troubleshooting Rsbuild projects.
rsbuild-v2-upgradeUse when upgrading a Rsbuild 1.x project to v2, including dependency and configuration updates.
rsdoctor-analysisUse when analyzing Rspack/Webpack bundles from local `rsdoctor-data.json` and producing evidence-based optimization recommendations.
rslib-best-practicesRslib best practices for config, CLI workflow, output, declaration files, dependency handling, build optimization and toolchain integration. Use when writing, reviewing, or troubleshooting Rslib projects.
rspack-debuggingHelps Rspack users and developers debug crashes or deadlocks/hangs in the Rspack build process using LLDB. Use this Skill when users encounter "Segmentation fault" errors during Rspack builds or when the build progress gets stuck.
rspack-split-chunks>-