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: