How to debug Node.js using the builtin debugger
Tags: node, javascript, debugging, tutorial
Published: 2021-07-20 07:35:41

It's about time you stop `console.log`ing 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:

```js
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][node-inspect].

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

```js
$ 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](https://nodejs.org/api/debugger.html), 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:

```js
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:

```js
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:

```js
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:

```js
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](https://nodejs.org/api/debugger.html) to learn more.

See you soon 👋!

[node-inspect]: https://github.com/nodejs/node-inspect