Debugger

Bun speaks the WebKit Inspector Protocol, so you can debug your code with an interactive debugger. For demonstration purposes, consider the following simple web server.

Bun.serve({
  fetch(req){
    console.log(req.url);
    return new Response("Hello, world!");
  }
})

--inspect

To enable debugging when running code with Bun, use the --inspect flag. This automatically starts a WebSocket server on an available port that can be used to introspect the running Bun process.

bun --inspect server.ts

------------------ Bun Inspector ------------------
Listening at:
  ws://localhost:6499/0tqxs9exrgrm

Inspect in browser:
  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
------------------ Bun Inspector ------------------

--inspect-brk

The --inspect-brk flag behaves identically to --inspect, except it automatically injects a breakpoint at the first line of the executed script. This is useful for debugging scripts that run quickly and exit immediately.

--inspect-wait

The --inspect-wait flag behaves identically to --inspect, except the code will not execute until a debugger has attached to the running process.

Setting a port or URL for the debugger

Regardless of which flag you use, you can optionally specify a port number, URL prefix, or both.

bun --inspect=4000 server.ts

bun --inspect=localhost:4000 server.ts

bun --inspect=localhost:4000/prefix server.ts

Debuggers

Various debugging tools can connect to this server to provide an interactive debugging experience.

debug.bun.sh

Bun hosts a web-based debugger at debug.bun.sh. It is a modified version of WebKit's Web Inspector Interface, which will look familiar to Safari users.

Open the provided debug.bun.sh URL in your browser to start a debugging session. From this interface, you'll be able to view the source code of the running file, view and set breakpoints, and execute code with the built-in console.

Let's set a breakpoint. Navigate to the Sources tab; you should see the code from earlier. Click on the line number 3 to set a breakpoint on our console.log(req.url) statement.

Then visit http://localhost:3000 in your web browser. This will send an HTTP request to our localhost web server. It will seem like the page isn't loading. Why? Because the program has paused execution at the breakpoint we set earlier.

Note how the UI has changed.

At this point there's a lot we can do to introspect the current execution environment. We can use the console at the bottom to run arbitrary code in the context of the program, with full access to the variables in scope at our breakpoint.

On the right side of the Sources pane, we can see all local variables currently in scope, and drill down to see their properties and methods. Here, we're inspecting the req variable.

In the upper left of the Sources pane, we can control the execution of the program.

Here's a cheat sheet explaining the functions of the control flow buttons.

• Continue script execution — continue running the program until the next breakpoint or exception.
• Step over — The program will continue to the next line.
• Step into — If the current statement contains a function call, the debugger will "step into" the called function.
• Step out — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.