debugging node

“If you’re good at the debugger it means you spent a lot of time debugging. I don’t want you to be good at the debugger.” ― Robert C. Martin

I’ve found myself trouble shooting code a lot lately - which has meant I’ve been stepping my way through a debugger pretty often. Working with Node, that’s meant I’ve seen a lot of references to the --inspect flag that you can use when you open a Node script. I’ve even seen a few references to --inspect-brk. Until today, however, I didn’t really understand how to use them (despite a cursory review of the documentation for getting started with debugging in Node).

Ultimately, I suggest reading that document as the answers are probably there. My goal with this post is to explain why you might use the --inspect or --inspect-brk flag as well as how you might integrate that into some workflows you like, such as debugging in VS Code or Chrome. (There are a few other CLI options as well related to specifying hosts/port.)

Let’s start at the top: why use the --inspect or --inspect-brk flag? Well, they both allow inspection of a Node script, but the former breaks immediately until a debugger has been attached to the process whereas the latter will break on breakpoints once a debugger’s been attached (as my telling might make clear, I’m a fan of the --inspect-brk, but if you have a reason to use just --inspect, please let me know!).

Imagine a small Node file, index.js:

function main(message) {
  console.log(message || "hello, world!")
}
const message = process.argv[2]
main(message)

If you pass a message, it will print it to stdout. If you don’t, you’ll see hello, world!. But now, we want to make sure that it’s working as expected.

We can run it from the shell:

node --inspect index.js

If we do it this way though, we need to be really fast to attach the debugger. In fact, I wasn’t fast enough and immediately I saw the output in the console:

Debugger listening on ws://127.0.0.1:9229/f5066c33-b025-44fd-a19c-d61612780e25
For help, see: https://nodejs.org/en/docs/inspector
hello

There was a listener on a websocket, but I didn’t get there fast enough (and I don’t have a debugger statement in line to tell my function to break, so the script ran to completion then exited.

So, let’s let Node help us out and break immediately:

 node --inspect index.js hello

In this case it feels like the opposite problem. Now, when I look at the console, it seems stuck:

Debugger listening on ws://127.0.0.1:9229/2eb58349-9720-45d4-986b-0ecd7d2db2dc
For help, see: https://nodejs.org/en/docs/inspector

This is because Node is waiting for me to attach a debugger. This is why half of the Getting Started guide is dedicated to Inspector Clients.

What does this actually mean though? Let’s walk through two:

1. VS Code
2. Chrome

Attaching Debuggers In VS Code

If you used --inspect-brk and Node’s now waiting on you, you can open the command palette (Cmd ⌘ + Shift ⇧ + P), we can use the Debug: Attach to Node Process.

This will open a menu of different node processes that can be attached to. In our case we’re looking for the one that matches the command that kicked off the whole process.

Once selected, we get the full debugger experience within VS Code:

Attaching Debugger In Chrom(ium)

If you’re using a Chromium-flavored browser (Chrome, Brave, Edge, etc.), you can attach a debugger in one of two ways:

1. If you open the Dev Tools, you can click on the Node icon to open a dedicated debugger for Node.js which will automatically attach the debugger.
2. You can navigate to chrome://inspect, one of the Chrome URLs, where you will the target. Clicking on inspect will open the dedicated debugger and attach to the process.

Wrap Up

Though, as Robert Martin suggests, it might be better if we didn’t have to be good at debugging, understanding how our tools work can come in handy.

Hopefully this walk through makes it a little more clear how you might take advantage of Node’s built in debugging processes!