rsbuild-best-practices

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

Guide developers through best practices for configuring, optimizing, and debugging Rsbuild projects.

  • Resolves configuration pitfalls and workflow questions across various build stages.
  • Provides guidance related to Rsbuild's internal CLI, configuration files, and build tooling.
  • Applies established rules for asset handling, type safety, and performance tuning.
  • Delivers actionable, categorized advice for improving project robustness and build quality.

SKILL.md

.github/skills/rsbuild-best-practicesView on GitHub ↗
---
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

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-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-best-practicesRspack best practices for config, CLI workflow, type checking, CSS, bundle optimization, assets and profiling. Use when writing, reviewing, or troubleshooting Rspack 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>-