rstackjs/rspack-debugging
skills/rspack-debugging/SKILL.md
Helps Rspack users and developers debug crashes or deadlocks/hangs in the Rspack build process using LLDB. Use this Skill when users encounter "Segmentation fault" errors during Rspack builds or when the build progress gets stuck.
$ install --global
skillsauthnpx skillsauth add rstackjs/agent-skills rspack-debuggingInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 18, 2026, 4:30 AM67.1s9 files scanned
SKILL.md
- name:
- rspack-debugging
- description:
- Helps Rspack users and developers debug crashes or deadlocks/hangs in the Rspack build process using LLDB. Use this Skill when users encounter "Segmentation fault" errors during Rspack builds or when the build progress gets stuck.
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.
-
Install LLDB: You must install the LLDB debugger.
- macOS: Run
xcode-select --install - Linux: Install the
lldbpackage (e.g.,apt-get install lldb) - Detailed guide: references/lldb.md
- macOS: Run
-
Replace Debug Packages: Production packages like
@rspack/corehave debug symbols stripped. They must be replaced with the@rspack-debug/*series packages to see useful stack information.Automatic Replacement Script:
node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjsRunning the above script will automatically add
pnpm.overridesconfiguration topackage.json, pointing Rspack packages to their corresponding Debug versions. Afterwards, please be sure to runpnpm installto 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
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
Guide C: Attach to Stuck Process
Scenario: Unstable Deadlock during Build (happens randomly). Read Guide: 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
Guide E: Coredump Analysis (Build)
Scenario: Unstable Crash during Build. Read Guide: 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
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.
- Create Directory: Ensure a directory named
debug_artifactsexists in the project root. - Save Backtraces: Write the full output of
thread backtrace alltodebug_artifacts/backtrace_<timestamp>.txt. - Save Tracing Logs: (Only if using Tracing Skill)
Environment Restoration
After debugging is complete, restore your package.json to use production packages:
node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs --restore
pnpm install
Related Skills
rstackjs/rstest-debugging
development
VerifiedTrustedCommunity
Debug Rstest issues systematically, including performance regressions. First determine whether the slowdown is in build startup or test execution, then run controlled config or code experiments and compare before/after timings.
68SKILL.mdUpdated May 21, 2026
rstackjs/rslib-modern-package
development
VerifiedTrustedCommunity
Opinionated Rslib recommendations for modern JS/TS npm package design covering pure ESM, strict TypeScript, explicit exports, small stable APIs, pragmatic dependencies, accurate sideEffects, correct declarations, package validation, provenance, README.md, and AGENTS.md. Use when the user wants to make a JS/TS package more modern, check whether the current package setup is healthy, review package.json/exports/types/dependencies/docs/release readiness, or apply a modern library baseline.
68SKILL.mdUpdated May 21, 2026
rstackjs/create-draft-release-notes
development
VerifiedTrustedCommunity
Create or update draft GitHub releases for the current project's main GitHub repository, then organize GitHub-generated release notes into user-friendly sections without rewriting release note items. Use for preparing, formatting, categorizing, creating, or updating GitHub release notes or draft releases, including optional highlights when the user asks for them.
68SKILL.mdUpdated May 21, 2026
rstackjs/migrate-to-rslint
tools
VerifiedTrustedCommunity
Migrate ESLint or other linters to Rslint. Use when asked to replace ESLint flat config, lint scripts, VS Code ESLint settings, inline directives, rules, presets, plugins, or lint dependencies with Rslint equivalents.
68SKILL.mdUpdated May 10, 2026