playbooks

home / skills / rstackjs / agent-skills / rspack-best-practices

rspack-best-practices skill

/skills/rspack-best-practices

This skill helps you apply Rspack best practices across config, CLI, CSS, assets, and profiling to streamline development and troubleshooting.

npx playbooks add skill rstackjs/agent-skills --skill rspack-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.5 KB
---
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

Overview

This skill documents practical Rspack best practices for configuration, CLI workflows, type checking, CSS handling, bundle optimization, asset management, profiling, and security. It is designed to speed up writing, reviewing, and troubleshooting Rspack projects by emphasizing clear defaults and measurable trade-offs. Use it as a checklist when creating or auditing builds.

How this skill works

The guidance inspects typical Rspack touchpoints: config shape, CLI commands, type check integration, CSS strategies, asset modules, bundle-splitting patterns, and profiling techniques. It prescribes explicit, narrow rules and prefers built-in Rspack features to reduce maintenance cost and improve performance. Follow the patterns to make builds predictable and easier to debug.

When to use it

  • Starting a new Rspack project or migrating from webpack
  • Reviewing or standardizing a mono-repo or multi-page app config
  • Optimizing bundle size or modernizing asset handling
  • Setting up CI type checks or local dev workflows
  • Diagnosing slow build/compile phases or runtime overhead

Best practices

  • Use rspack.config.ts with defineConfig and explicit entry points for multi-page apps
  • Keep one main config and branch on NODE_ENV only when necessary
  • Make rule conditions narrow and explicit (test/include/exclude/resourceQuery)
  • Prefer built-in Rspack plugins/loaders before adding community alternatives
  • Use ts-checker-rspack-plugin or tsc --noEmit/vue-tsc --noEmit for type checking
  • Choose a single CSS strategy and prefer asset modules over legacy loaders

Example use cases

  • Set up dev workflow with `rspack dev`, production build with `rspack build`, and `rspack preview` for local production testing
  • Switch from babel-loader/PostCSS/terser to Rspack built-ins when profiling shows those stacks are slow
  • Use dynamic import() for non-critical routes to reduce initial bundle size
  • Import images and fonts from src and reference public files by absolute URL paths
  • Enable RSPACK_PROFILE=OVERVIEW to generate trace output and identify compiler-phase bottlenecks

FAQ

Should I publish production .map files?

No. Avoid publishing source maps to public servers or CDNs for production builds to protect source exposure.

Which CSS approach should I pick?

Prefer built-in CSS handling for modern projects. Use css-loader + CssExtractRspackPlugin for webpack migration or style-loader for runtime injection scenarios.