Debugging in Bun.js

🪛 Debugging in Bun.js: Catch Bugs Like a Pro

Bun.js is known for its lightning-fast performance and modern JavaScript tooling—but even the fastest tools don’t save you from bugs 🐞. That’s where smart debugging comes in. Whether you're new to Bun or transitioning from Node.js, this guide will show you practical ways to debug your Bun.js applications effectively using built-in tools, external strategies, and some Bun-specific tips.

🔍 Why Debugging in Bun is Different

Unlike traditional Node.js environments, Bun combines multiple tools like the runtime, bundler, transpiler, and test runner into a single binary. This fusion makes debugging more streamlined but also slightly different from what most devs are used to. Bun also aims to give cleaner stack traces and faster feedback, but knowing how to tap into these features is key 🔑.

🛠️ Using console.log() – The Classic Start

Sometimes, good old console.log() is all you need. You can log values at different stages of execution to get quick feedback. Here’s a simple example:

// index.ts
function calculateDiscount(price: number): number {
  console.log("Original price:", price);
  const discount = price * 0.1;
  console.log("Discount:", discount);
  return price - discount;
}

console.log("Final price:", calculateDiscount(200));

Run it using:

bun index.ts

⚠️ Tip: Use console.error() to highlight unexpected issues in red in most terminals.

🧵 Understanding Stack Traces in Bun

When an error is thrown, Bun shows a clean, readable stack trace pointing to the exact file and line:

TypeError: Cannot read properties of undefined (reading 'length')
    at calculateLength (file:///project/utils.ts:4:19)
    at main (file:///project/index.ts:10:5)

✅ Pro Tip: Bun’s stack traces are fast and readable thanks to native support for source maps, even when using TypeScript.

🧠 Using the Debugger with Bun

Want to go deeper? Bun supports the Chrome DevTools debugging protocol via the --inspect flag. To enable it:

bun --inspect index.ts

This will open a debugging endpoint (usually on localhost:9229). Open Chrome and navigate to chrome://inspect, then click “Open dedicated DevTools for Node”. You can set breakpoints and step through code just like in a browser! 🔎

🧪 Debugging Tests with Bun

Debugging your tests is just as important. Bun allows you to add logging inside test files or even inspect:

// add.test.ts
import { test, expect } from "bun";
import { add } from "../src/math";

test("adds numbers", () => {
  const result = add(2, 3);
  console.log("Testing add result:", result);
  expect(result).toBe(5);
});

Then run:

bun test

Or for deeper inspection:

bun --inspect test add.test.ts

🧰 Debugging with Bun + VS Code

If you're using VS Code, debugging Bun projects is easy. Just configure your launch.json like so:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Bun App",
      "program": "${workspaceFolder}/index.ts",
      "runtimeExecutable": "bun",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

This setup allows you to add breakpoints, watch variables, and control execution step-by-step inside the editor 🧑‍💻.

🔄 Watching Files for Changes

While not a traditional debugger feature, automatic reloading can help during debugging sessions. Use:

bun --watch run index.ts

Your script will re-run every time you change the file—super useful when fixing bugs or tweaking logic quickly 🔁.

🧱 Isolating Bugs with Mini Tests

When you're not sure what's breaking, extract the suspected code block into a standalone test or script:

// debug-snippet.ts
function isEven(n: number) {
  return n % 2 === 0;
}

console.log("isEven(4):", isEven(4));
console.log("isEven(5):", isEven(5));

This method helps you isolate logic and validate assumptions without running the full app.

💡 Pro Debugging Tips

• Use breakpoints when logs aren’t enough
• Always check types, especially in TypeScript
• Keep test coverage high to prevent hidden bugs
• Disable optimizations if behavior seems off
• Use try/catch blocks around suspected areas

✅ Conclusion

Debugging in Bun.js doesn't have to be hard. With built-in stack traces, support for DevTools inspection, and a test-friendly runtime, Bun offers all the essentials you need to squash bugs efficiently 🔨. Whether you're logging, stepping through code, or isolating snippets, these techniques will help you become a faster, sharper Bun developer.