Debugger Mode in Node.js - How to Debug Node.js Applications

Not many people are aware that Node.js includes a command-line debugging utility. Debugging Node.js applications is quite simple if you know what to do.

Let’s explore this useful utility and learn how to use it.

The debugger statement

During debugging, we might want to pause execution of our code so that we can inspect some variables. To do so, we can use the debugger statement, like so:

script.js:

function greet(name) {
  debugger;
  return `Hello, ${name}`;
}
greet("Pumpkin");

When the JavaScript interpreter executes this block of code, it will pause, allowing us to inspect some of the variables within the block. This makes it much easier to debug our applications, as we can see precisely what is going on when our code executes.

NOTE: When using the debugger statement, you must call the function you want to inspect.

Inspecting the file

$ node inspect script.js
< Debugger listening on ws://127.0.0.1:9229/6be29c46-2bb6-4e8b-89c5-a108ad53d32a
< For help, see: https://nodejs.org/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
Break on start in script.js:5
  3   return `Hello, ${name}`;
  4 }
> 5 greet("Pumpkin");
  6
debug>

After running node inspect script.js, the code is paused at line 1, nothing is running. To tell the inspector to continue running the code, we can type cont (for continue) or simply c.

debug> c
break in script.js:2
  1 function greet(name) {
> 2   debugger;
  3   return `Hello, ${name}`;
  4 }
debug>

After we run c, the interpreter will run our file, line by line, until it finds the debugger statement. Once it gets to the debugger statement, it pauses, and allows you to inspect some of the variables inside the function.

If we want to actually inspect our variables, we can’t simply type them in the terminal at this point, we’ll have to enter a repl mode.

debug> name
REPL2:1
name
^

Uncaught ReferenceError: name is not defined
    at REPL2:1:1
    at Script.runInContext (node:vm:139:12)
    at Object.runInContext (node:vm:289:6)
    at REPLServer.controlEval (node:internal/debugger/inspect_repl:576:25)
    at bound (node:domain:421:15)
    at REPLServer.runBound [as eval] (node:domain:432:12)
    at REPLServer.onLine (node:repl:891:10)
    at REPLServer.emit (node:events:520:28)
    at REPLServer.emit (node:domain:475:12)
    at REPLServer.[_onLine] [as _onLine] (node:internal/readline/interface:389:12)
debug>

Entering REPL mode

REPL stands for Read, Evaluate, Print, Loop. It is a programming environment which provides a convenient way to test our JavaScript code. To enter REPL mode, we’ll simply run the command repl:

debug> repl
Press Ctrl+C to leave debug repl

Now we’re in a JavaScript console, where we can start to inspect variables which exist in our codebase, like so:

> name
'Pumpkin'

We can even bring in some of our code from the script.js file to audit it’s functionality with our variables.

> `Hello there, ${name}.`
'Hello there, Pumpkin.'

So you might get an idea of how this can be quite useful if we have large files, and want to test our variable’s behavior, we can inspect it to see exactly how it’s working. We’ve explored the basics of debugger mode. Experiment with it a bit, and learn how to use it to your benefit, it can be quite useful if you find yourself confused by some code.