Debugging

Debugging with VS Code

1. Install go install github.com/go-delve/delve/cmd/dlv@latest
2. Install VS Code extension rust-analyzer and CodeLLDB
3. build @rspack/cli and napi binding by run pnpm install && pnpm -w build:cli:dev
4. In VS Code's Run and Debug tab, select Debug Rspack to start debugging the initial launch of @rspack/cli with a simple rspack project. This task can be configured in .vscode/launch.json.

Using @rspack-debug/core

Frameworks and tools that integrate Rspack usually depend on the release build of @rspack/core. The release package is suitable for normal builds, but it does not include some debug-only capabilities. When you need these capabilities for local investigation, override @rspack/core with @rspack-debug/core in the project that runs the build.

For example, with pnpm:

{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-debug/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}

Then reinstall dependencies and run the original build command again. For example, if the project builds through Rsbuild:

pnpm install
RSPACK_PROFILE=OVERVIEW RSPACK_TRACE_LAYER=perfetto rsbuild build

@rspack-debug/core should only be used for local debugging and diagnostics. Prefer pinning it to the same version as the original @rspack/core dependency when investigating a version-specific issue, and remove the override after the investigation.

Common debugging scenarios guide

Debugging Rust

Simply set breakpoints in the specified Rust code and start Debug Rspack to begin debugging.

Debugging JavaScript

When starting Debug Rspack, select the --inspect or --inspect-brk option, then start Attach JavaScript and choose the PID of the corresponding process.

Debugging a running Rspack process

When Rspack is integrated into other frameworks or tools (such as Nx), it may be difficult to independently start Rspack in Launch mode. In this case, you can debug the code through attach mode. Start Attach Rust and select the PID of the Rspack process, and start Attach JavaScript to debug JavaScript.

Debugging a Rspack process with a deadlock

When using Attach Rust to attach the debugger to the Rspack process, click the Pause button on the Debugger to set breakpoints at the deadlock scene.

rust-lldb

rust-lldb can be used to get panic information from debug builds

rust-lldb -- node /path/to/rspack build

Once it launches, press r for running the program.

For example, examples/arco-pro crashes without any information before this fix:

rspack/examples/arco-pro ❯ node ../../packages/rspack-cli/bin/rspack build
Rspack ██████████████████████░░░░░░░░░░░░░░░░░░ 56% building ./pages/welcome
zsh: bus error  node ../../packages/rspack-cli/bin/rspack build

Using rust-lldb

rspack/examples/arco-pro ❯ rust-lldb -- node ../../packages/rspack-cli/bin/rspack build

Press r and it prints:

Process 23110 stopped
* thread #10, name = 'tokio-runtime-worker', stop reason = EXC_BAD_ACCESS (code=2, address=0x70000cc66560)
    frame #0: 0x0000000140d0db4b rspack.darwin-x64.node`swc_ecma_parser::parser::expr::ops::_$LT$impl$u20$swc_ecma_parser..parser..Parser$LT$I$GT$$GT$::parse_unary_expr::h29f49330a806839c(self=0x0000000000000000) at ops.rs:244
   241 	    /// Parse unary expression and update expression.
   242 	    ///
   243 	    /// spec: 'UnaryExpression'
-> 244 	    pub(in crate::parser) fn parse_unary_expr(&mut self) -> PResult<Box<Expr>> {
   245 	        trace_cur!(self, parse_unary_expr);
   246 	        let start = cur_pos!(self);
   247
Target 0: (node) stopped.