home / skills / rstackjs / agent-skills / rspack-tracing

rspack-tracing skill

safe

This skill helps diagnose Rspack build slowdowns, identify slow plugins, and analyze trace files to optimize performance.

npx playbooks add skill rstackjs/agent-skills --skill rspack-tracing

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

Files (4)

SKILL.md

2.7 KB

---
name: rspack-tracing
description: Comprehensive guide and toolkit for diagnosing Rspack build issues. Quickly identify where crashes/errors occur, or perform detailed performance profiling to resolve bottlenecks. Use when the user encounters build failures, slow builds, or wants to optimize Rspack performance.
---

# 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 to run the bundled analysis script on the generated trace file.

```bash
# Navigate to the generated profile directory
cd .rspack-profile-*/

# Run the analysis script
node ${CLAUDE_PLUGIN_ROOT}/skills/tracing/scripts/analyze_trace.js 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`.

Overview

This skill is a comprehensive guide and toolkit for diagnosing Rspack build issues and performing performance profiling. It helps you quickly find where builds crash or slow down, and provides concrete steps to capture traces, run analyses, and interpret results. Designed for JavaScript projects, it focuses on locating slow plugins, loaders, and problematic hooks.

How this skill works

The skill walks you through capturing a trace by enabling Rspack profiling environment variables and producing a trace.json file. It shows quick commands to inspect the tail of the trace for crash stages and provides a bundled analysis script to run a full performance profile. Finally, it explains how to map span and hook names from the analysis to specific plugins or configuration lines for actionable fixes.

When to use it

You have a failing or crashing Rspack build and need to find which stage failed.
Build times are unexpectedly slow and you need to identify bottlenecks.
You have a trace.json produced by Rspack and want a guided analysis.
You want to map slow hooks to plugins or configuration lines.
You need step-by-step instructions to capture a performance profile.

Best practices

Always run the build with RSPACK_PROFILE=TRACE and set RSPACK_TRACE_OUTPUT to a writable directory.
For quick crash diagnosis, inspect the last 20 events of trace.json using tail before running full analysis.
Run the provided analyze_trace.js script in the generated profile directory for a detailed breakdown.
Use the mapping guide to translate span names and hook names into plugin files and config lines.
Capture reproducible builds and share the trace.json and relevant config (rspack.config.js or rsbuild.config.ts) when asking for help.

Example use cases

Diagnosing an immediate build crash: capture trace, cd into .rspack-profile-*/ and tail trace.json to see the final span.
Finding a slow plugin: run full analysis script and inspect "Top Slowest Hooks" to locate the responsible plugin and file paths.
Optimizing build performance: collect multiple traces to compare run-to-run variability and identify consistent bottlenecks.
Guiding a user through producing a trace.json so you can analyze it remotely and point to exact lines in plugin source.

FAQ

What command generates the trace file?

Run the build with profiling enabled, for example: RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json pnpm build.

How do I quickly see where a build failed?

Change into the generated .rspack-profile-* directory and run tail -n 20 trace.json to view the last events and find the failing span or plugin.