The simple guide to debug Next.js apps in VSCode

Cover Image for The simple guide to debug Next.js apps in VSCode
Marouane Reda
Marouane Reda
If you need to understand the basics of Next.js, i recommend this course. (Disclaimer : this is an affiliate link that may earn me a small commission, but with no extra cost to you if you choose to enroll)

Debugging your code is important if your app is showing an unwanted behaviour or errors. We will see in this article how to debug a Next.js app in VSCode, one pf the most popular IDEs.

Debugging a Next.js app in VSCode requires 3 simple steps :

Start Next.js in debug mode As Next.js is essentially a Node.js app, you only need to use the --inspect flag to the underlying Node.js process for it to start in debug mode. First, start Next.js with the inspect flag:

NODE_OPTIONS='--inspect' next dev

or modify the dev script on your package.json if you use npm run dev or yarn dev:

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

Connect to the debugger

We will be using the attach mode of VS Code to attach the VS Code inspector to our running debugger started in step 1.

Create a file named .vscode/launch.json at the root of your project with this content:

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

Now hit F5 or select Debug: Start Debugging from the Command Palette and you can start your debugging session.

Put breakpoints and start debugging

You can start debugging by adding conditionnal breakpoints, logs, ...

all the details for debugging in VSCode can be found here.