Skip to main content
skill CX Codex

rspack-debugging — Claude Code skill: debug native Rspack crashes

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.

MIT 282 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-debugging -a claude-code
Open on GitHub

What rspack-debugging does

The skill walks an agent through capturing the crash state of native Rspack. Rspack runs on Rust, so a segfault or a deadlock only shows up at stack level; the skill gets LLDB to produce a detailed backtrace. The run is non-interactive, with the agent driving the debugger and collecting output.

Six guides cover the scenarios: a crash during HMR, a crash during a build, attaching to a process that hangs, coredump analysis for dev and for build, and tracking an async deadlock where the main thread sits in uv_run. Preparation is handled by scripts/setup_debug_deps.cjs, which writes pnpm.overrides into package.json and points the packages at the @rspack-debug/* series.

Skip that swap and the backtrace tells you little: production packages such as @rspack/core ship with symbols stripped. LLDB has to be there too, via xcode-select --install on macOS or the lldb package on Linux. When debugging ends, rerun the script with --restore and pnpm install to put production packages back. Whatever backtrace the agent obtains goes to debug_artifacts/backtrace_<timestamp>.txt in the project root.

What it helps with

  • catch a backtrace when a Rspack build segfaults
  • diagnose HMR that hangs DevServer
  • attach a debugger to a stuck build process
  • read a coredump from an intermittent crash
  • find an async deadlock with the main thread in uv_run

Example prompts for the agent

  • The Rspack build crashed with a segfault — grab a backtrace with LLDB and save it under debug_artifacts.
  • HMR keeps freezing DevServer, walk the HMR crash guide.
  • Swap the packages to debug builds with scripts/setup_debug_deps.cjs, then restore them when we're done.

How to install rspack-debugging

1Skills CLI (Vercel)

npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-code

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rspack-debugging

How do I install rspack-debugging in Claude Code?

Run npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-code. The skill lands at ~/.claude/skills/rspack-debugging/SKILL.md.

What does rspack-debugging do?

It guides the agent through capturing Rspack's crash state: start LLDB, pull the stack, save it as a file inside debug_artifacts.

What has to be in place before debugging?

LLDB, plus the package swap that scripts/setup_debug_deps.cjs performs by pointing dependencies at the @rspack-debug/* series, followed by pnpm install. Production packages have their symbols stripped, so a stack from them is of little use.

Source text

SKILL.md · MIT
---
name: rspack-debugging
description: Debug native Rspack crashes, segmentation faults, deadlocks, or stuck builds with LLDB and matching debug symbols.
---

# Rspack debugging

## Overview

This Skill guides you on how to capture the underlying crash state of Rspack (which is based on Rust). By using the LLDB debugger and Rspack packages with debug symbols, we can obtain detailed stack backtraces, which are crucial for pinpointing issues. The guides focus on non-interactive, automated debugging to easily capture backtraces.

## Preparation

Before starting, please ensure your environment meets the requirements.

1.  **Install LLDB**: You must install the LLDB debugger.
    - macOS: Run `xcode-select --install`
    - Linux: Install the `lldb` package (e.g., `apt-get install lldb`)
    - Detailed guide: [references/lldb.md](references/lldb.md)

2.  **Replace Debug Packages**:
    Production packages like `@rspack/core` have debug symbols stripped. They must be replaced with the `@rspack-debug/*` series packages to see useful stack information.

    **Automatic Replacement Script**:

    Resolve the bundled [`scripts/setup_debug_deps.cjs`](scripts/setup_debug_deps.cjs)
    relative to the Skill root while keeping the working directory in the user's
    project, then run:

    ```bash
    node "<skill-root>/scripts/setup_debug_deps.cjs"
    ```

    Running the above script will automatically add `pnpm.overrides` configuration to `package.json`, pointing Rspack packages to their corresponding Debug versions. Afterwards, please be sure to run `pnpm install` to update dependencies.

## Debugging workflows

Identify your specific scenario and follow the corresponding linked guide.

## Detailed guides

## Detailed guides

### Guide A: crash during HMR

**Scenario**: Stable Crash/Deadlock during DevServer HMR.
[Read Guide: references/guide_a_hmr_crash.md](references/guide_a_hmr_crash.md)

### Guide B: crash during build

**Scenario**: Stable Crash/Deadlock during Build (or Unstable Build Crash that is frequent enough).
[Read Guide: references/guide_b_build_crash.md](references/guide_b_build_crash.md)

### Guide C: attach to stuck process

**Scenario**: Unstable Deadlock during Build (happens randomly).
[Read Guide: references/guide_c_attach_to_stuck_process.md](references/guide_c_attach_to_stuck_process.md)

### Guide D: coredump analysis (Dev)

**Scenario**: Unstable Crash during DevServer HMR (hard to catch interactively).
[Read Guide: references/guide_d_coredump_analysis_dev.md](references/guide_d_coredump_analysis_dev.md)

### Guide E: coredump analysis (Build)

**Scenario**: Unstable Crash during Build.
[Read Guide: references/guide_e_coredump_analysis_build.md](references/guide_e_coredump_analysis_build.md)

### Guide F: async deadlock identification

**Scenario**: Unstable Async Deadlock. Main thread stuck in `uv_run`.
[Read Guide: references/guide_f_async_deadlock.md](references/guide_f_async_deadlock.md)

## Saving debug artifacts

**Critical Instruction for Agents**:
When you successfully obtain a backtrace or a tracing log, you **MUST** save it to a local file in the user's project directory so it is preserved after the session.

1.  **Create Directory**: Ensure a directory named `debug_artifacts` exists in the project root.
2.  **Save Backtraces**: Write the full output of `thread backtrace all` to `debug_artifacts/backtrace_<timestamp>.txt`.
3.  **Save Tracing Logs**: (Only if using Tracing Skill)

## Environment restoration

After debugging is complete, restore your `package.json` to use production packages:

```bash
node "<skill-root>/scripts/setup_debug_deps.cjs" --restore
pnpm install
```

Use the same resolved `<skill-root>` as in Preparation.

© rstackjs · MIT · rstackjs/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set21

The whole set →
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-tracing 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. CX Codex +1 291installs 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 rspress-v2-upgrade The rspress-v2-upgrade skill automates upgrading an Rspress project from v1 to v2. It reads the config, updates dependencies, rewrites import paths, and validates the build against the official migration guide. CX Codex +1 150installs

Project sponsors

Companies that keep this analytics open