Let’s face it…debugging Node.js is (and always has been) kind of a pain.

Enter the Pain of Debugging in Node.js

If you’ve ever had the pleasure of writing code for a Node.js project, you know what I’m talking about when I say debugging it to figure out what’s going wrong isn’t the easiest thing.

Unlike JavaScript in the browser, or Java with a powerful IDE like IntelliJ, you can’t just set breakpoints everywhere, refresh the page or restart the compiler and slowly walk through the code examining objects, evaluating functions and finding the mutation or missing variable, etc. You just can’t, and it stinks.

But it is possible to debug, it just takes a little more elbow grease. Let’s go over the options and then I’ll show you the easiest way I’ve come across in my own development.

Options to Debug in Node.js

There’s a number of ways to debug your misbehaving Node.js program, I’ve listed them out below with links to learn more if you so desire.

Console.log() — the tried and true standby, this one really needs no further explanation if you’ve ever written a line of JavaScript. It’s built in to Node.js and prints in the terminal just like it’s built into JavaScript and prints in the browser’s console.

In Java, it’s System.out.println() in Python, it’s print() , you get the idea. This is the easiest one to implement, and it’s the fastest way to litter your clean code with extra lines of info — but it can also (sometimes) help you find and fix the error.

Node.js documentation —-inspect — The Node.js docs themselves understand debugging isn’t the easiest, so they’ve made a handy reference to help get people started.

It’s useful, but honestly, unless you’ve been programming for a while, it’s not exactly the easiest thing to decipher. They pretty quickly go down the rabbit hole of UUIDs, WebSockets, and security implications and I start to feel in over my head. And thinking to myself: there’s got to be a less complex way to do this.

Chrome DevTools — Paul Irish wrote a great blog post back in 2016 (updated in 2018) about debugging Node.js using Chrome DevTools, and from the looks of things it sounded pretty simple, and like a great step forward for debugging.

Fast forward half an hour, and I still hadn’t managed to connect a DevTools window to my simple Node program and I wasn’t so sure anymore. Maybe I just can’t follow directions, but Chrome DevTools seems to make it more complicated to debug than it should be.

JetBrains — one of my very favorite software development companies and makers of IntelliJ and WebStorm to name just a few IDEs, JetBrains is great. They’ve got a fantastic ecosystem of plugins for their tools and until recently, they were my go-to IDE without question.

With such a dedicated user base came lots of helpful articles like this, which walk through debugging Node, but similar to the Node documentation and the Chrome DevTools options, it’s not easy. You have to create a debugging configuration, attach running processes and do a good bit of configuration in the preferences before WebStorm is ready to go.

Visual Studio Code — this is my new gold standard for Node debugging. I never thought I’d say it, but I am all in on VS Code, and every new feature release the team does, makes me love this IDE more.

VS Code does what every other option for debugging Node.js fails to do, it makes it stupid simple. If you want to get fancier with your debugging you absolutely can, but they break it down to make it simple enough anyone can get up and running quickly, regardless of how familiar you are with IDEs, Node, programming, etc. And it’s awesome.

Setting up VS Code To Debug in Node.js

Sorry, I couldn’t resist this meme — it’s just so appropriate. Ok, so let’s walk through setting up VS Code to debug Node. I’ll assume you’ve already downloaded VS Code from the link I posted above, so we’re ready to start setting it up.

Open up Preferences > Settings and in the search box type in “node debug”. Under the Extensions tab there should be one extension titled “Node debug”. From here, click the first box: Debug > Node: Auto Attach and set the drop down to “on”. You’re almost ready to go now. Yes, it really is that easy.