How to Debug Bun Applications with VS Code: Complete Configuration Guide

Debug Bun applications in VS Code by installing the official oven.bun-vscode extension, configuring .vscode/launch.json with "type": "bun", and pressing F5 to launch or attach to the Bun runtime.

The Bun VS Code extension provides first-class debugging support for JavaScript and TypeScript projects running on the Bun runtime. According to the oven-sh/bun source code, the extension integrates directly with Bun's WebKit Inspector protocol to enable breakpoints, variable inspection, and live error reporting. This guide covers the complete setup process using the official configurations documented in packages/bun-vscode/README.md.

Installing the Bun VS Code Extension

Install the Bun extension (ID: oven.bun-vscode) from the VS Code Marketplace. The extension automatically registers the Bun language server and debugger adapter, enabling debug support for .js, .ts, and .tsx files without additional tooling.

Configuring launch.json for Bun Debugging

Create a .vscode/launch.json file in your project root to define debug profiles. The extension supports two primary request types: "launch" to start a new Bun process, and "attach" to connect to an already running process.

Launch Configuration (New Process)

Use "request": "launch" to start your application under the debugger. The "type": "bun" field tells VS Code to use the Bun debug adapter.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Bun (watch)",
      "program": "${file}",
      "args": [],
      "cwd": "${workspaceFolder}",
      "env": {},
      "strictEnv": false,
      "watchMode": true,
      "stopOnEntry": false,
      "noDebug": false,
      "runtime": "bun",
      "runtimeArgs": []
    }
  ]
}

Key fields include:

• watchMode: Set to true for --watch or "hot" for --hot hot-reloading
• runtimeArgs: Passes arguments directly to the Bun executable (e.g., --inspect)
• stopOnEntry: Pauses execution on the first line when set to true

Attach Configuration (Running Process)

Use "request": "attach" to debug a Bun process started with the inspector flag.

bun --inspect src/index.ts

# Output: ws://127.0.0.1:6499/

Then configure the attach profile:

{
  "type": "bun",
  "request": "attach",
  "name": "Attach to Bun (inspect)",
  "url": "ws://127.0.0.1:6499/",
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app"
}

The url field must match the WebSocket endpoint printed by bun --inspect or bun --inspect-brk.

Enabling the Debug Terminal and Global Settings

Add Bun to the built-in JavaScript Debug Terminal and configure global behavior in .vscode/settings.json:

{
  "bun.runtime": "/usr/local/bin/bun",
  "bun.debugTerminal.enabled": true,
  "bun.debugTerminal.stopOnEntry": false,
  "bun.test.filePattern": "**/*{.test.,.spec.,_test_,_spec_}{js,ts,tsx,jsx,mts,cts,cjs,mjs}",
  "bun.test.customScript": "bun test"
}

The bun.debugTerminal.enabled setting adds Bun support to VS Code's integrated debug terminal, allowing you to launch debug sessions from the command palette. The bun.test.filePattern setting configures the test runner integration for the extension's test explorer.

Watch Mode and Hot Reloading Support

Combine debugging with Bun's native watch mode by setting watchMode: true in your launch configuration. This is equivalent to running bun --watch and automatically restarts the debugger when files change.

For hot module reloading (preserving state where possible), set watchMode: "hot" to invoke bun --hot. Pair this with stopOnEntry: false to maintain a continuous debug session across reloads without breaking on startup.

Inline Error Reporting

When a runtime error occurs, Bun sends the exact source location to the VS Code extension via the inspector protocol documented in packages/bun-inspector-protocol/README.md. The extension displays inline diagnostics—red squiggly lines at the error location with hover tooltips containing stack traces—without requiring additional configuration.

For advanced debugging of Bun itself (native C++ internals), the repository provides LLDB pretty-printers in misctools/lldb/README.md and debug build instructions in CONTRIBUTING.md.

Summary

• Install the oven.bun-vscode extension from the VS Code Marketplace to enable Bun debugging
• Configure "type": "bun" in .vscode/launch.json with either "request": "launch" or "request": "attach"
• Start attach debugging by running bun --inspect and connecting to the printed WebSocket URL
• Enable watchMode: true or "hot" in launch configurations for automatic reloading during debug sessions
• Use bun.debugTerminal.enabled in settings to add Bun to VS Code's built-in JavaScript Debug Terminal

Frequently Asked Questions

How do I install the Bun debugger for VS Code?

Install the official extension (ID: oven.bun-vscode) from the VS Code Marketplace. The extension is developed and maintained in the oven-sh/bun repository under packages/bun-vscode/ and provides the debug adapter for Bun applications.

What is the difference between launch and attach modes?

Launch starts a new Bun process under the debugger using the entry point specified in program, while Attach connects to an existing process that was started with bun --inspect or bun --inspect-brk. Use attach when you need to debug a process already running in a terminal or container.

How do I enable hot reloading while debugging?

Set watchMode: true in your launch configuration for standard file watching (equivalent to --watch), or use watchMode: "hot" for hot reloading (equivalent to --hot). Combine with stopOnEntry: false to prevent the debugger from pausing on every reload.

Can I debug Bun tests in VS Code?

Yes. Configure bun.test.filePattern in .vscode/settings.json to match your test files, and use bun.test.customScript to specify the test runner command. The extension integrates with VS Code's test explorer to run and debug individual tests with full breakpoint support.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}