rspack-tracing — Claude Code skill: profile Rspack builds
rspack-tracing — a skill for Claude Code and other IDEs that captures and analyzes Rspack build traces to pinpoint slow compiler phases, plugins, and loaders. Diagnose performance bottlenecks and crashes during development.
MIT 291 installs ★ 100 updated 2026-10-22
npx skills add rstackjs/agent-skills --skill rspack-tracing -a claude-codeWhat rspack-tracing does
The skill walks the agent through four steps: enable tracing via environment variables (RSPACK_PROFILE=TRACE), quickly check the last events in the trace file to spot crashes, run analysis through the bundled analyze_trace.mjs script, then map span names to specific plugins in the config.
For crash diagnosis, just view the last 20 lines of the trace with tail. For full performance profiling, the script outputs the slowest hooks and identifies which plugin is responsible. The agent then shows file paths and line numbers for suspected plugins.
Requires Node.js and pnpm (or another package manager). Traces are saved to .rspack-profile-{timestamp}-{pid}/ with trace.json inside.
What it helps with
- identify why an Rspack build runs slowly
- find which plugin or loader causes delays
- pinpoint the compiler phase where a crash occurred
- analyze a user-provided trace file
Example prompts for the agent
- Help me find why my Rspack build is slow
- Analyze my trace.json and tell me which plugin is causing delays
- My build crashed—which compiler stage failed?
How to install rspack-tracing
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-tracing -a claude-code2Manually: put the files in place
~/.claude/skills/rspack-tracing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rspack-tracing/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-tracing -a codex2Manually: put the files in place
.agents/skills/rspack-tracing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-tracing -a cursor2Manually: put the files in place
.cursor/skills/rspack-tracing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rstackjs/agent-skills skills/rspack-tracing2Manually: put the files in place
.github/skills/rspack-tracing/SKILL.md1Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-tracing -a gemini-cli2Platform CLI
gemini skills install https://github.com/rstackjs/agent-skills --path skills/rspack-tracingManually: put the files in place
.devin/skills/rspack-tracing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-tracing -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 rspack-tracing
How do I install rspack-tracing in Claude Code?
Run npx skills add rstackjs/agent-skills --skill rspack-tracing -a claude-code, then open ~/.claude/skills/rspack-tracing/SKILL.md.
What does rspack-tracing do?
It helps locate slow phases and plugins in Rspack builds. The agent enables tracing, analyzes the output, and points you to which code is causing delays.
What do I need to use it?
You need Node.js and pnpm (or npm/yarn). The skill works with your existing rspack.config.js or rsbuild.config.ts.
Source text
SKILL.md · MIT
---
name: rspack-tracing
description: Capture or analyze Rspack build traces to locate slow compiler phases, plugins, loaders, or the last events before a build failure.
---
# Rspack tracing & performance profiling
## When to use this skill
Use this skill when you need to:
1. Diagnose why an Rspack build is slow.
2. Understand which plugins or loaders are taking the most time.
3. Analyze a user-provided Rspack trace file.
4. Guide a user to capture a performance profile.
## Workflow
### 1. Capture a trace
First, ask the user to run their build with tracing enabled.
```bash
# Set environment variables for logging to a file
RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json pnpm build
```
This will generate a trace file in a timestamped directory like `.rspack-profile-{timestamp}-{pid}/trace.json`.
See [references/tracing-guide.md](references/tracing-guide.md) for more details on configuration.
### 2. Quick diagnosis for Crashes/Errors
If the user wants to identify **which stage a crash or error occurred in**, use `tail` to quickly view the last events without running the full analysis:
```bash
# Navigate to the generated profile directory
cd .rspack-profile-*/
# View the last 20 events to see where the build failed
tail -n 20 trace.json
```
The last events will show the span names and targets where the build stopped, helping to quickly pinpoint the problematic stage, plugin, or loader.
### 3. Full performance analysis
For detailed performance profiling (not just crash diagnosis), ask the user whether to run the bundled [`scripts/analyze_trace.mjs`](scripts/analyze_trace.mjs) on the generated trace file. If they agree, resolve it relative to the Skill root while keeping the working directory in the user's project, then run:
```bash
# Navigate to the generated profile directory
cd .rspack-profile-*/
# Run the analysis script
node "<skill-root>/scripts/analyze_trace.mjs" trace.json
```
### 4. Interpret results
Use the output from the script to identify bottlenecks.
Consult [references/bottlenecks.md](references/bottlenecks.md) to map span names to actionable fixes.
### 5. Locate slow plugins
Based on the "Top Slowest Hooks" from the analysis script:
1. **Identify the Hook**: Note the hook name (e.g., `hook:CompilationOptimizeChunks`).
2. **Inspect Configuration**: Read `rspack.config.js` or `rsbuild.config.ts`.
3. **Map Hook to Plugin**: Look for plugins and their sources that tap into that specific hook.
4. **Output**: Output the paths, lines and columns of the suspected plugin source code.
## Common scenarios & quick fixes
- [Bottleneck Reference](references/bottlenecks.md): Mapping spans to concepts.
- [Tracing Guide](references/tracing-guide.md): Detailed usage of `RSPACK_PROFILE`.
© rstackjs · MIT · rstackjs/agent-skills