Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rstackjs/agent-skills --skill rspack-tracing -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/rspack-tracing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rspack-tracing/

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

Similar skills

All skills for Frontend and UI →

From the same set21

The whole set →
migrate-to-rstest migrate-to-rstest migrates Jest, Vitest, or Playwright Test suites to Rstest while keeping test discovery, assertions, mocks, snapshots, and coverage intact. For moving a runner without rewriting scenarios. CX Codex +1 436installs rspress-custom-theme rspress-custom-theme — a skill that walks your agent through Rspress v2 theme changes, from CSS variables up to replacing built-in components. CX Codex +1 435installs rspress-docs-generator rspress-docs-generator builds a new Rspress v2 docs site or updates existing documentation pages according to changes in source code and tests. CX Codex +1 344installs migrate-to-rsbuild migrate-to-rsbuild — a skill that migrates webpack, Vite, Create React App, and Vue CLI projects to Rsbuild. It rewrites build configs and validates dev servers before cleaning up old packages. CX Codex +1 342installs rspack-debugging rspack-debugging captures the crash state of native Rspack with LLDB: backtraces for segfaults, deadlocks and builds that hang. Useful when the failure sits inside Rust. CX Codex +1 282installs storybook-rsbuild The storybook-rsbuild skill sets up Storybook with Rsbuild or migrates an existing project from webpack or Vite. It also handles integrations with Rslib, Modern.js, and Rspack. CX Codex +1 212installs migrate-to-rslib migrate-to-rslib converts TypeScript library builds from tsc or tsup to Rslib with validation before cleanup. CX Codex +1 201installs rspack-split-chunks rspack-split-chunks teaches the agent to diagnose and tune optimization.splitChunks in Rspack: find duplicate modules, over-fetching, cache group issues, and oversized chunks. CX Codex +1 187installs

Project sponsors

Companies that keep this analytics open