rsbuild-best-practices — Claude Code skill: how to install
Provides rules for configuring, reviewing, and troubleshooting Rsbuild applications. Helps agents inspect builds, handle assets, and profile performance.
npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a claude-codeWhat rsbuild-best-practices does
This skill instructs the agent to write clean rsbuild.config.ts files using defineConfig. It treats direct modifications in tools.rspack or tools.bundlerChain as a last resort, prioritizing built-in Rsbuild options to prevent subtle configuration drift. For multi-page projects, the agent defines explicit entries in source.entry and resolves TypeScript paths through tsconfig.json.
Build optimization and asset handling follow strict guidelines. Type checking runs either via @rsbuild/plugin-type-check or standalone scripts with tsc --noEmit. Managed assets must be imported from project source folders rather than public, while public files are referenced by absolute path. When source maps are enabled for production, .map files must never be deployed to public CDNs.
Debugging requires hard verification instead of guesses. The agent inspects the final resolved configuration files in dist/.rsbuild or runs commands with DEBUG=rsbuild. For compiler bottlenecks, it relies on trace analysis triggered by RSPACK_PROFILE=OVERVIEW.
What it helps with
- configure
rsbuild.config.tswithout raw Rspack overrides - verify generated build configs in
dist/.rsbuild - wire up type checking with
@rsbuild/plugin-type-check - optimize bundle size using dynamic
import() - diagnose compiler bottlenecks using
RSPACK_PROFILE=OVERVIEW
Example prompts for the agent
- Inspect my
rsbuild.config.tsand set up entry points for a multi-page setup. - Show me how to debug configuration resolution using
DEBUG=rsbuild. - Configure production source maps without exposing
.mapfiles on public CDNs.
How to install rsbuild-best-practices
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/rsbuild-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rsbuild-best-practices/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a codex2Manually: put the files in place
.agents/skills/rsbuild-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a cursor2Manually: put the files in place
.cursor/skills/rsbuild-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rstackjs/agent-skills rsbuild-best-practices2Manually: put the files in place
.github/skills/rsbuild-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/rstackjs/agent-skills --path skills/rsbuild-best-practicesManually: put the files in place
.devin/skills/rsbuild-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about rsbuild-best-practices
How do I install rsbuild-best-practices in Claude Code?
Run npx skills add rstackjs/agent-skills --skill rsbuild-best-practices -a claude-code to install the skill. The file is placed in ~/.claude/skills/rsbuild-best-practices/SKILL.md.
What does rsbuild-best-practices do?
It establishes guidelines for configuring and debugging Rsbuild setups. The skill ensures agents use official options, manage assets cleanly, and avoid publishing production source maps.
How does the skill handle build profiling and diagnostics?
The rules direct the agent to check dist/.rsbuild directly instead of assuming values. For deep profiling, it uses --cpu-prof for JavaScript overhead and RSPACK_PROFILE=OVERVIEW for compiler stalls.
Source text
SKILL.md · MIT
--- name: rsbuild-best-practices description: Configure, review, or troubleshoot Rsbuild applications, including build/dev commands, assets, type checking, and bundle optimization. --- # 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` 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
© rstackjs · MIT · rstackjs/agent-skills
