bun-dap-x

Standalone Debug Adapter Protocol (DAP) server for debugging Bun programs through the Bun Inspector.

bun-dap-x speaks DAP over stdin/stdout. Configure your editor or DAP client to spawn the adapter, then use a normal DAP launch or attach request.

Install

bun add -d bun-dap-x

Use the published binary from a DAP client with:

bunx bun-dap-x

From a source checkout:

bun install
bun run start

bun run start starts the adapter and waits for DAP messages on stdin; it is not an interactive debugger UI.

Launch and attach basics

For launch, pass the Bun program in program:

{
	"type": "bun-dap-x",
	"request": "launch",
	"name": "Debug Bun file",
	"program": "${file}",
	"cwd": "${workspaceFolder}",
	"runtime": "bun",
	"args": [],
	"runtimeArgs": [],
	"env": {},
	"stopOnEntry": false
}

Supported launch arguments:

• program (required): script to run with Bun.
• cwd: working directory for the debuggee. Defaults to the adapter process cwd.
• runtime or runtimeExecutable: Bun executable. Defaults to bun.
• runtimeArgs: arguments before program.
• args: arguments after program.
• env: environment overrides.
• strictEnv: when true, use only env; otherwise merge with the adapter environment.
• stopOnEntry: when true, keep Bun's initial inspector pause.
• disableTestTimeout: when omitted or true, bun test launches get --timeout=0 unless args or runtimeArgs already contain --timeout; set false to preserve Bun's default timeout.

For attach, start Bun with the inspector enabled and attach to the WebSocket URL that Bun prints:

bun --inspect=127.0.0.1:6499 ./src/index.ts

{
	"type": "bun-dap-x",
	"request": "attach",
	"name": "Attach to Bun inspector",
	"url": "ws://127.0.0.1:6499/<inspector-id>"
}

Attach also accepts inspectorUrl, or host, port, and path fields. The default host is 127.0.0.1; the default port is 6499. path is still required unless you pass a full url/inspectorUrl, because Bun's Inspector HTTP endpoint does not expose the per-process WebSocket path. For *.test.* and *.spec.* targets, attach disables Bun's test timeout before resume; set disableTestTimeout to false to opt out, or to true for nonstandard Bun test filenames.

VS Code

VS Code launch configurations require a debug extension to register the bun-dap-x debug type. The extension manifest should contribute the type:

{
	"contributes": {
		"debuggers": [
			{
				"type": "bun-dap-x",
				"label": "Bun DAP X"
			}
		]
	}
}

Then register the standalone adapter executable from the extension:

import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
	context.subscriptions.push(
		vscode.debug.registerDebugAdapterDescriptorFactory("bun-dap-x", {
			createDebugAdapterDescriptor() {
				return new vscode.DebugAdapterExecutable("bunx", ["bun-dap-x"]);
			},
		}),
	);
}

After the debug type is registered, use a .vscode/launch.json configuration such as:

{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "bun-dap-x",
			"request": "launch",
			"name": "Bun: current file",
			"program": "${file}",
			"cwd": "${workspaceFolder}",
			"runtime": "bun"
		},
		{
			"type": "bun-dap-x",
			"request": "attach",
			"name": "Bun: attach",
			"url": "ws://127.0.0.1:6499/<inspector-id>"
		}
	]
}

For a local checkout of this repository, point the descriptor at the source entrypoint instead:

new vscode.DebugAdapterExecutable("bun", ["/absolute/path/to/bun-dap-x/src/cli.ts"]);

Neovim / nvim-dap

local dap = require("dap")

dap.adapters["bun-dap-x"] = {
	type = "executable",
	command = "bunx",
	args = { "bun-dap-x" },
}

dap.configurations.javascript = {
	{
		type = "bun-dap-x",
		request = "launch",
		name = "Bun: current file",
		program = "${file}",
		cwd = "${workspaceFolder}",
		runtime = "bun",
		args = {},
		runtimeArgs = {},
		stopOnEntry = false,
	},
	{
		type = "bun-dap-x",
		request = "attach",
		name = "Bun: attach",
		url = "ws://127.0.0.1:6499/<inspector-id>",
	},
}

dap.configurations.typescript = dap.configurations.javascript

For a local checkout:

dap.adapters["bun-dap-x"] = {
	type = "executable",
	command = "bun",
	args = { "/absolute/path/to/bun-dap-x/src/cli.ts" },
}

Supported features

• Launch Bun programs and attach to Bun Inspector WebSocket sessions.
• Source breakpoints, including pending breakpoints set before launch.
• Function breakpoints for unique loaded static function declarations/assignments found by source scanning.
• Conditional breakpoints, hit-count breakpoints, and logpoints.
• Exception breakpoints for Bun Inspector's uncaught/all pause modes.
• Continue, pause, step over, step in, step out, terminate, and disconnect.
• Stack traces, scopes, variables, hover evaluation, and REPL evaluation.
• Debuggee stdout, stderr, and console output as DAP output events.
• Loaded sources and breakpoint-location queries.
• Set-variable, completion, and modules requests backed by Bun Inspector state.
• Best-effort Bun source-map support for TypeScript/TSX/MTS/CTS/JSX sources, imported files, and generated lines that do not map directly back to source.

Limitations

• One debug target and one DAP thread are exposed per adapter process.
• Attach requires a Bun Inspector WebSocket URL, or explicit host/port/path; PID attach and host/port-only discovery are not supported because Bun 1.3.14 returns only version metadata from /json/version, returns 404 for /json and /json/list, and rejects WebSocket connections without the exact inspector path.
• The adapter does not provide a terminal for debuggee stdin; launched processes run with stdin ignored.
• Data and instruction breakpoints are not implemented because Bun Inspector does not expose data watchpoints or instruction-address breakpoints.
• Restart, memory, and disassembly requests are not implemented; memory and disassembly remain unsupported because Bun Inspector does not expose safe byte-read/disassembly backing.
• Source-map and source-level stepping behavior is best-effort and follows Bun Inspector output.

Development

bun install
bun run start
bun run test
bun run typecheck
bun run check
bun run format

Additional maintenance scripts:

bun run knip
bun run jscpd

Versioning and releases

Releases are managed by release-please from Conventional Commits.

• fix: ... creates a patch release.
• feat: ... creates a minor release.
• feat!: ... or a BREAKING CHANGE: footer creates a major release.