How to debug Node.js using the builtin debugger

It's about time you stop console.loging to debug code.
Here, I'll show you how to use the builtin Node.js debugger.

Most of you might be using your IDEs debugger to debug code, but did you know that Node.js has a built in debugger? It's simple, but extremely powerful. Here, I'll show you how to use the builtin debugger.

Prerequisites

You need to have Node.js installed, obviously. You also need to know JavaScript because you can't debug without writing code.

The code

For this example, we will be debugging this code:

const importantNumbers = "1123, 435, 8712, 843"
let res = 0;

importantNumbers.split(', ').forEach(number => res += number);

console.log(res);
// => NaN
// Why?

If you've been coding for a while, I'm pretty sure you already have spotted the mistake, but just assume that you haven't

You can copy and paste this code to a new file if you want to follow along.

Debugging with Node.js

How it works

You can run the debugger by running node --inspect file.js. This opens a WebSocket connection to something like ws://127.0.0.1:9229/uuid-here. Now, clients can connect to this debugger and debug code. You can even build your own clients!

Node.js has a built in client which we can use by running
node inspect file.js (notice it's a command, not an option now). You can install the latest standalone version of this command by installing node-inspect.

If you run node inspect file.js, you should get some output like this:

$ node inspect file.js
< Debugger listening on ws://127.0.0.1:9229/d7d8aec2-819b-411a-abdd-900b6b90dbfc
< For help, see: https://nodejs.org/en/docs/inspector
< Debugger attached.
Break on start in file.js:1
> 1 const importantNumbers = "1123, 435, 8712, 843"
  2 let res = 0;
  3 
debug> 

You'll get a special debug prompt which is used to run commands. You can check out the reference, but I'll show you some commands here.

These commands are available:

• cont, c: Continue execution
• next, n: Step next
• step, s: Step in
• out, o: Step out
• pause: Pause running code (like pause button in Developer Tools)

So, we can now jump to the next line by typing n and hitting enter. We'll then get output like this:

debug> n
break in file.js:2
  1 const importantNumbers = "1123, 435, 8712, 843"
> 2 let res = 0;
  3 
  4 importantNumbers.split(', ').forEach(number => res += number);
debug> 

As you can see, the debugger has jumped to the next line. If your terminal supports colors, you will see the 0 has been highlighted as it is the next step.

Hit next again. You'll get this:

debug> n
break in resources/debugging.js:4
  2 let res = 0;
  3 
> 4 importantNumbers.split(', ').forEach(number => res += number);
  5 
  6 console.log(res);
debug> 

Notice how the debugger skipped an empty line for us.

Now, we're reaching the important parts. Let's watch our important variables:

debug> watch('number')
debug> watch('res')
debug> 

Since this is an important line, we can step instead of going to the next line. So type s and hit enter, and you'll get this:

debug> s
break in file.js:4
Watchers:
  0: number = '1123'
  1: res = 0

  2 let res = 0;
  3 
> 4 importantNumbers.split(', ').forEach(number => res += number);
  5 
  6 console.log(res);
debug> 

You can see watched variables at the top. res is 0 and number is '1123'. We can easily understand that number + string = NaN.

That was a pretty basic introduction to debugging Node.js. There's much more to learn. You can check out the docs to learn more.

See you soon 👋!