playbooks

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

rsbuild-best-practices skill

/skills/rsbuild-best-practices

This skill helps you write and review rsbuild projects by applying best practices for config, CLI, type checking, bundling, assets, and debugging.

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

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

Files (1)
SKILL.md
1.9 KB
---
name: rsbuild-best-practices
description: Rsbuild best practices for config, CLI workflow, type checking, bundle optimization, assets, and debugging. Use when writing, reviewing, or troubleshooting Rsbuild projects.
---

# 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 dev` 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

Overview

This skill captures Rsbuild best practices for config, CLI workflow, type checking, bundle optimization, asset handling, debugging, and profiling. It is intended to guide engineers writing, reviewing, or troubleshooting Rsbuild projects. The content focuses on concrete, actionable rules that reduce build errors, shrink bundles, and speed up iteration cycles.

How this skill works

The skill summarizes recommended patterns for rsbuild.config.ts usage, CLI commands, and TypeScript integration so teams adopt consistent workflows. It highlights where to prefer first-class Rsbuild options versus lower-level rspack/bundlerChain hooks and explains debugging and profiling steps to diagnose config and compile issues. Practical rules on assets, public files, source maps, and runtime imports help maintain security and optimize bundle size.

When to use it

  • When starting a new Rsbuild project or converting an existing build to Rsbuild
  • During code reviews to validate config and CLI usage
  • While troubleshooting build failures, unexpected bundle size, or runtime asset problems
  • When adding TypeScript or optimizing production bundles
  • When preparing production deployments and verifying source map/security settings

Best practices

  • Centralize config in rsbuild.config.ts and export via defineConfig for predictable resolution
  • Prefer first-class Rsbuild options; use tools.rspack or tools.bundlerChain only if no native option exists
  • Declare explicit source.entry values for multi-page apps to avoid ambiguous bundling
  • Integrate type checks either with @rsbuild/plugin-type-check or via tsc/vue-tsc --noEmit scripts
  • Use dynamic import() for non-critical code, choose lightweight libraries, and align browserslist with real target browsers
  • Import source-managed assets from src; reference static files in public by absolute URL and avoid publishing .map files publicly

Example use cases

  • Create rsbuild.config.ts with defineConfig, explicit entries, and path alias precedence from tsconfig.json
  • Run rsbuild dev for local iteration, rsbuild build for production, and rsbuild preview only to locally validate the production output
  • Add @rsbuild/plugin-type-check in CI for build-time type validation or run tsc --noEmit in a prebuild step
  • Refactor large synchronous modules to dynamic import() to reduce initial bundle cost
  • Enable DEBUG=rsbuild to trace plugin resolution and inspect dist/.rsbuild for computed final config

FAQ

Should I always use tools.rspack in the config?

No. Use first-class Rsbuild options when available. Resort to tools.rspack or tools.bundlerChain only when no native option supports your need.

How do I avoid shipping source maps publicly?

Disable publishing .map files to public servers or CDNs for production builds. Keep source maps in private artifact storage or restrict access.