Debugging Node.js with V8 Inspector

Node.js seems to increase in both popularity and sophistication on a daily basis. The project recently scored a major feature, as support for the V8 Inspector was merged into Node's master branch. This gives Node applications direct integration with DevTools, the top notch debugging tools that ship with Google Chrome. Unlike previous tools like Node Inspector, there are no required external dependencies except Chrome. The Chrome Debugging Protocol, used by V8 Inspector, can also communicate with tools from other vendors such as Microsoft and Firefox.

How do I use it?

At the time of writing (June 14, 2016), V8 Inspector hasn't been included in any official Node releases, but is expected to ship as an unofficial feature very soon. You must build Node's master branch in order to experiment with it today. As previously mentioned, you'll also need Chrome. Once you've built Node from source, launch a Node application with the --inspect flag, as shown below.

$ node --inspect app.js

This will run your application with the Inspector listening on its default port of 9229. You can change the port to 5000 for example, using --inspect=5000. You can also combine --inspect with other command line flags such as --debug-brk, to automatically add a breakpoint on application startup.

When your application starts, it will print a link to the console:

To start debugging, open the following URL in Chrome:
chrome-devtools://devtools/remote/serve_file/@521e5b7e2b7cc66b4006a8a54cb9c4e57494a5ef/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node

The specifics of the URL are not important, and it is subject to change in the future. Copy the entire URL, starting with chrome-devtools:// into the Chrome address bar. This will open DevTools and allow you to begin debugging your application. If you've used DevTools before, this is no different - you should be able to jump right in.

Looking forward

As previously mentioned, the protocol used by the V8 Inspector is not proprietary. Other vendors are already working to integrate their debuggers with V8 Inspector. This has raised the question as to whether or not it is appropriate to print a Chrome specific URL at startup. There have also been issues reported regarding the convenience of selecting the URL from a Windows console.

While the future of the V8 Inspector is still being ironed out, I have released the Node.js V8 Inspector Chrome Extension that allows two click attachment to the debugger. Once you've installed the extension, start your application with the --inspect flag. Then, click on the Node.js V8 Inspector icon in your browser. Once you've selected the correct port, click the Launch V8 Inspector button. This will launch DevTools and allow you to debug your application. Enjoy!