Debugging Node.js applications (part 1)
As developers, we frequently spend a hefty amount of time debugging. It is for this reason that knowing how to properly debug is crucial if we want to be productive.
In this series we are going to kick the good old console.log out of our lives and learn how to debug node.js the right way.
Fundamentals
Before we start we need to know that node.js uses the Chrome V8 engine under the hood. The V8 engine is a low level piece of software written in C++ that translates our JS code to machine code.
The Chrome V8 engine implements a protocol called the V8 Inspector Protocol or Chrome Debugging Protocol. This protocol has been available since node 6.3 and it provides debugging clients with a way to communicate with the engine itself.
To demonstrate how we can debug a piece of code we are going to run a simple HTTP “Hello world” server in debug mode.
This is the code for the server:
The built-in node debugger
Many people don’t know it, but Node.js comes packed with it’s own debugging client. We can run the previous example in debug mode using the command node inspect:
The code execution stops at the start of the script. The prompt changes to debug> and we can start typing some commands. Typing help will print a list with all the available commands.
Now we are going to set a breakpoint inside the request handler. We use the setBreakpoint function to set a breakpoint in the line 7. Then we use the cont function to let the code execution flow.
Now we can go to http://localhost:3000/ and the script will stop at the request handler. Once it stops we use the repl command to launch a REPL. This REPL will let you evaluate expressions in the current context.
There are many other useful commands in the builtin inspector but we are not going to cover them here. The builtin debugger is nice when we need to do some quick debugging but there are better clients.
Using third party debuggers
In our previous example we used node inspect to run our code. What this command does is tell node to run our code listening for inspector commands via websockets on ws://localhost:9229/, and then it runs the builtin debugging client connected to that socket.
We can use the --inspect or the --inspect-brk CLI flag to just run the code in debug mode and then use a third party debugger to attach to the inspector. The only difference between the two is that --inspect-brk stops the execution at the start of the script and the --inspect does not.
Chrome Developer Tools
We can attach to the running process using the Chrome Developer Tools. With the debugger listening, go to chrome://inspect and you will see something like this:
Clicking the link will open the Chrome Developer Tools window and automatically attach the debugger to the running process. We can do mostly the same things we could do with the builtin debugger but the interface is way better.
If you are using macOS, You can use this small script to open the node.js Chrome Developer Tools directly from the command line.
Visual Studio Code
We could also use Visual Studio Code to attach to the node process. To do this, open your script with vscode, press SHIFT+CMD+P and type attach to node process. This will list all the processes you can attach to. Choose the process listening to port 9229 and you will be ready to debug.
Using ndb
Ndb is a new node debugger done by Google. It uses Puppeteer to launch the Chrome Developer Tools, but has some nice extra features.
You can easily install ndb with npm or yarn:
$ npm i -g ndb
$ yarn global add ndbOnce installed, just prepend ndb before the thing you want to debug and the Chrome Developer Tools will automatically open attached to the process:
$ ndb node main.jsWrapping it up
In this post we have learned how to attach our debugger to a node process. In the next part of this series we will cover the basics of the Chrome developer tools and we will use the debugger to fix a real bug.
