5 Steps to debugging Next.js/Node.js from VSCode or Chrome DevTools

April 5, 2020 update: This article is now part of the Next.js documentation: https://nextjs.org/docs/advanced-features/debugging

---

👋 Hi there, this article explains how to setup your developer environment so you can debug your Next.js application using Visual Studio Code debugger or Chrome DevTools.

Since Next.js is a Node.js application, what's provided here as guidance will also work for any Node.js program.

When fully setup, you'll be able to put breakpoints in both frontend (React) and backend code (Node.js, API routes). Then your favorite debugger will pop out whenever your code encounters your breakpoints.

The whole tutorial takes 5 min. When you'll be finished, you'll get this experience (VS Code, React):

Table of contents:

• Mandatory introduction: why even bother?
• Step one: create your Next.js debugging demo application
• Step two: configure Next.js to start in debug mode
• Step three: launch your application
• Step four: connect your debugging inspector
  • VS Code
  • Chrome DevTools
• Step five: actually debug your application

Mandatory introduction: why even bother?

I always thought that I don't need a debugger in JavaScript: I can just console.log my way out most of the time. The reason for this habit I believe is that JavaScript debugging tools were always kind of working but not really. In the browser at least it was working but then Node.js came and it was again very hard to debug it nicely. The whole debugging experience was painful and you spent more time switching windows than anything else.

Now after using VS Code to debug both my React and Node.js code I really think it's way more powerful than a regular console.log(obj) > reload page > switch to a terminal (🔁 repeat with console.log(obj.property...) flow.

Give it a try, you'll "enjoy" it.

I will be using a fresh create-next-app example to demonstrate how it works.

Step one: create your Next.js debugging demo application

You can skip to step two if you already have a Next.js application

in a terminal:

> npx create-next-app
✔ What is your project named? … demo-nextjs-debugging
# wait...
> cd create-next-app

Step two: configure Next.js to start in debug mode

Edit the file package.json and change this part:

  "scripts": {
-   "dev": "next",
+   "dev": "NODE_OPTIONS='--inspect' next",
  }

If you have a different way of launching Next.js, just make sure that NODE_OPTIONS='--inspect' is always right before the next command.

I like to change the default dev command so that anytime I am in developer mode, I can start a debugging session in one shortcut (more on that in step four).

Be aware that using NODE_OPTIONS='--inspect' npm run dev or NODE_OPTIONS='--inspect' yarn run dev won't work. This would try to start multiple debuggers on the same port: one for the npm/yarn process and one for Next.js. You would then get an error like Starting inspector on 127.0.0.1:9229 failed: address already in use in your console.

NODE_OPTIONS is a standard Node.js flag.

Step three: launch your application

in a terminal:

> yarn dev
yarn run v1.22.0
$ NODE_OPTIONS='--inspect' next dev
Debugger listening on ws://127.0.0.1:9229/6bd49cb3-e640-4d76-ad88-86480e167df7
For help, see: https://nodejs.org/en/docs/inspector
[ wait ]  starting the development server ...
[ info ]  waiting on http://localhost:3000 ...
[ ready ] compiled successfully - ready on http://localhost:3000

Step four: connect your debugging inspector

This is a convoluted title but it just means connecting either VS Code debugging feature or Chrome DevTools to your Next.js application.

VS Code

You can also skip to the chosen solution.

There are multiple ways to connect the VS Code inspector to your Next.js application running in debug mode. All of that is explained in VS Code gigantic Node.js debugging documentation page.

You can either:

1. Configure VS Code to actually start your Next.js application for you and connect to its debugger. Frankly, this is not my favorite solution because usually all developer environments are already using some sort of process manager like node-foreman, ❤️ overmind, docker-compose, heroku local, nodemon. So... No!
2. Start your Next.js application from within the internal terminal of VS Code so it detects it. Same as 1., I don't use the internal VS Code terminal, I have a side terminal already.
3. Configure VS Code so that it connects to your already started Next.js application. ✅ That's what I like.

---

Here's how to do it:

Create .vscode/launch.json at the root of your project:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Launch Program",
      "skipFiles": [
        "<node_internals>/**"
      ],
      "port": 9229
    }
  ]
}

Save it. Now hit F5 on your keyboard or go click on "Run and Debug (F5)" in the 🐞 debugging panel of VS Code. You should get this:

As you can see, you now have the full VS Code inspector connected to your Next.js application. It even shows the console output.

Now, whenever you think "Hmm, I wonder what's not working, what does this variable really holds". Just hit F5 in VS Code, trigger the underlying code (page refresh, click..) and enjoy a nice debugging experience!

Bonus: If your Next.js code is not at the root of your workspace

If your Next.js project is not at the root of your VSCode workspace, then you need to add:

.vscode/launch.json

{
  // ...
  "configurations": [
    {        
      // ...
      "sourceMapPathOverrides": {
        "webpack:///./*": "${workspaceRoot}/subfolder/*",
      }
    }
  ]
}

Thanks ubermensh for the tip!

Chrome DevTools

If you prefer to debug your Next.js application using the regular Chrome DevTools, all you have to do now is open a new tab in Chrome with the url being: chrome://inspect.

You'll see this:

Click on "inspect" and the Chrome DevTools are now connected to your Next.js application.

Step five: actually debug your application

Now all you have to do is setup breakpoints in your application. Either by adding the debugger; keyword anywhere in your code or by clicking on the left of a line to turn it into a breakpoint in VS Code editor or Chrome.

Whenever you do so and the underlying code runs (page load, page click, api call...) then a debugging UI will popup.

How to use VS Code or Chrome debugging tools is better explained by their own docs:

• VS Code Node.js debugging: Breakpoints
• Get Started with Debugging JavaScript in Chrome DevTools

---

🔚 That's it!

🙏 Thank you for reading.

Did you enjoy this post? Any advice as for Next.js or Node.js debugging? Add a thank you note or advice in the comments and I'll reply :)

Click below to share this post:

Comments

[pom421]

It just doesn't work :(.

On a Mac OS, with create-next-app in version 9.1.1.

npx create-next-app
"scripts": {
"dev": "NODE_OPTIONS='--inspect' next",

I run yarn dev and terminal displays:

$ NODE_OPTIONS='--inspect' next
Starting inspector on 127.0.0.1:9229 failed: address already in use

[Vincent Voyer]

Hey there, there's currently a bug in Next.js about this, I opened a PR here: github.com/zeit/next.js/pull/11041

I updated the blog post too.

But in Next.js 9.1.1 it should have been working weirdly. Are you starting different Node.js processes from Next.js? Or maybe you have a Next.js plugin that is doing so. Let me know!

[pom421]

Thanks for the quick answer.

This is the package.json after npx create-next-app:

{
"name": "test",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "NODE_OPTIONS='--inspect' next dev",
"build": "next build",
"start": "next start"
},
"dependencies": {
"next": "9.3.1",
"react": "16.13.1",
"react-dom": "16.13.1"
}
}

Everything seems up to date, yet :

yarn dev

yarn run v1.22.0
$ NODE_OPTIONS='--inspect' next dev
Debugger listening on ws://127.0.0.1:9229/dc491c88-ca40-47d2-8568-26ea554a4ae4
For help, see: https://nodejs.org/en/docs/inspector
[ wait ] starting the development server ...
[ info ] waiting on http://localhost:3000 ...
Starting inspector on 127.0.0.1:9229 failed: address already in use
Starting inspector on 127.0.0.1:9229 failed: address already in use
Starting inspector on 127.0.0.1:9229 failed: address already in use

And when I inspect for the port 9229, nothing is bound to.
lsof -nP -iTCP:9229 | grep LISTEN -> no line

[Vincent Voyer]

Hey there, can you try with next@9.2? I know this version was working because I used the debugging on it.

[pom421]

Good guess! It works with Next 9.2.0 and not in 9.3.1...

I will wait for your PR to be merged so, because I don't want to downgrade the version for this only debug need.

Thanks for your help!

[Sambhav Gore]

I followed it exactly but could not get it to work.
Shows Debugger attached, but when I add breakpoints, it stops at other code places which is not my code and stepping through just goes past where I wanted it to stop.
If I enter debugger; statements they are simply ignored. it never stops on those.

I am on nextjs 9.4.0 with node 13.13.0 and latest VSCode on Ubuntu 18.04

[Helmut Drewes]

Did you manage to solve the issue. Have exactly the same problem.

[Sambhav Gore]

no I did not.

[Roman Kraiovsky 🇺🇦🇸🇪]

Hey, thanks for the post!
It works well with Next front-end, but setting breakpoints in VS Code for APIs does not work - VS Code complains "Breakpoint set but not yet bound". Setting debugger does work though.
Do you know why and how to make IDE breakpoints work?

[Vincent Voyer]

Hmm it's weird, following the exact same guide I do have breakpoints in API routes working well. So really don't know what to tell you.. Try to create a simple repository and see if you're having the same issue, share it with me and I will also test it.

Thanks  🙏

[S.R. Aman]

Hey, Great article.
But I don't think it is working as of now.
I am still getting

> NODE_OPTIONS='--inspect' next

Debugger listening on ws://127.0.0.1:9229/2b4b791d-9654-4de5-9226-c2816116b1ac
For help, see: https://nodejs.org/en/docs/inspector
[ wait ]  starting the development server ...
[ info ]  waiting on http://localhost:3000 ...
Starting inspector on 127.0.0.1:9229 failed: address already in use
Starting inspector on 127.0.0.1:9229 failed: address already in use...

[Ramiro Herrera]

Hi there, thanks for making this guide :)

I'm stuck at step three with the following error in console

'NODE_OPTIONS' is not recognized as an internal or external command,
operable program or batch file.
error Command failed with exit code 1.

I solved following the steps on this post stackoverflow.com/questions/539485... and replacing the dev config with this one: "dev": "cross-env NODE_OPTIONS='--inspect' next",

My problem is, debugger doesn't seem to work. I used the same breakpoints, the same 'test' variable as in the video example, but I get nothing on my debugger tabs (variables, watch, etc.) when I run it

[Stuart Tett]

I'm constantly having this issue with debugging Next.js API routes. Often I can't place breakpoints in vscode, or if I do it breaks at some totally random spot (sometimes it will open the correct transpiled file and then I can just move the breakpoint to where it should be).

The only chance I have is to stop my server, restart vscode, blow away the the .next directory, and restart. But as soon as I change some code, I have to do it all over again.

I feel like there must be some trick to it, otherwise, I feel like i'd see more complaints about it.

{
      "type": "node",
      "request": "attach",
      "name": "Attach to Program",
      "skipFiles": [
        "<node_internals>/**"
      ],      
      "port": 9229
    },

"dev": "NODE_OPTIONS='--inspect' next dev",

[Pinesh I Menat]

My Two cents:

NextJS under the hood is ReactJS so I tried adding launch.json of react from VSCode

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "pwa-msedge",
      "request": "launch",
      "name": "Launch Edge against localhost",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}"
    }
  ]
}

Now run NextJS as "dev": "next dev" - no change
npm run dev
Press F5 to attch the process and it should work now.

[Ricardo Martins]

Vscode always stop at the first line, no matter what you configure it to.

It ignores the skipFiles, stopOnEntry, etc.

Any idea why?

[Eunjae Lee]

I don't know the exact difference, but for those of you who get address already in use issue,

try

"dev": "node --inspect node_modules/.bin/next",

[Vincent Voyer]

Hi there, which command were you using previously when getting "address already in use"? The blog post and documentation warns about this so I thought it would be good. The error comes from the fact that NODE_OPTIONS is sent to all child node processes so when running NODE_OPTIONS=.. yarn dev you're asking yarn to start in debugger mode and also nextjs, on the same port, which causes this error.

Also, you should be able to safely remove node_modules/.bin/ because that's already the default when running npm scripts.

[Eunjae Lee]

Hey, embarrassingly, I do not remember which command I was using yesterday. (It was literally yesterday, though)

anyway you're saying

NODE_OPTIONS='--inspect' next
node --inspect node_modules/.bin/next

These two commands are equivalent?
I didn't know. Thank you!

[Vincent Voyer]

I do not know if both of those commands are equivalent, what I know is that:

{
  "scripts": {
    "dev": "next"
  }

and

{
  "scripts": {
    "dev": "./node_nodules/.bin/next"
  }

are equivalent, because of: docs.npmjs.com/misc/scripts#path

What I wanted to say is that:

running

NODE_OPTIONS='--inspect' yarn dev

will fail because this starts two processes in debugger mode: yarn and nextjs. This is why you get the error message about already running debugging server.

NODE_OPTIONS can only be passed right next to the next command inside package.json.

[Victor Cheeney]

It looks like the problem with NODE_OPTIONS has been fixed, I'm not getting the Starting inspector on 127.0.0.1:9229 failed: address already in use error anymore. 🙂 However, I can't seem to get the clientside debugging working. I installed the Debugger for Chrome extension in VS Code, but I think that I miss a certain launch.json attach configuration? Excellent tutorial, thank you!

[Vincent Voyer]

Yes you do need a launch.json configuration, and I don't think you need a particular extension on VSCode, just the regular current installation.

The launch.json configuration is inside the blog post, did you use it?

You can also first try the Google Chrome debugging method also highlighted in this blog post which requires less configuration.