Debugging Next.js 15.x Apps in VS Code or Cursor

This is a very short post about debugging front and backend Next.js code with breaking points. No one writes flawless code, in fact, we tend to write junk code at first and iterate over it until we get it right. This is why debugging is an essential skill for developers. But lately I tried to debug some complex Next.js apps and realized how hard it is to debug bloated frameworks.

With Next.js we actually have to distinguish between the frontend and the backend. The frontend is the part of the application that runs in the browser, while the backend is the part that runs on the server - like React Server Components (RSC) and Serverless Functions like Route Handlers.

Frontend Debugging

Well this is the easiest part. Just open your browser's dev tools. And then you can add the debugger; statement to every component that has the 'use client' directive at the top of the file. And when this client-side component/code is executed, the debugger will pause the execution automatically.

What you can also do is to search for the file names of 'use client'-files in the dev tools Sources tab. In Chrome the easiest way to do this is with Ctrl + P and then type the file name. In the file you can then activate breaking points and enjoy the debugging experience.

Backend Debugging

This one is slightly more complicated to pull off but nothing that a good blog post couldn't cover. First you need to understand what backend code is in terms of Next.js. With backend code we are talking about React Server Components (RSC) and Serverless Functions like Route Handlers. So every file without 'use client' at the top of the file is backend code and so is every route.ts file and 'use server' block.

First you need to modify your npm run dev ever so slightly or make a new dev:debug script by adding a NODE_OPTIONS environment variable to enable debugging. I like to set a debugging port that is not used typically like 9400. But Next somehow also uses the next Port namely 9401. So your dev script inside the package.json file should look like the following.

  "dev:debug": "NODE_OPTIONS='--inspect=localhost:9400' next dev",
  "dev:debugcrossplattform": "cross-env NODE_OPTIONS='--inspect=localhost:9400' next dev",

Bonus tip: You can also use cross-env to set the environment variable cross-platform as windows handles environment variables differently than unix-based systems.

Now when running your dev script you should see something like:

Debugger listening on ws://localhost:9400/53876187-cad6-435f-a168-7d77c0be8d4f
For help, see: https://nodejs.org/en/docs/inspector

The next step is to add a .vscode/launch.json file if you don't have one already. This file is used by VS Code to configure the debugger. There you need to add the following configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
        "name": "Attach to Next Backend",
        "port": 9402,
        "request": "attach",
        "type": "node",
        "skipFiles": ["<node_internals>/**"]
    },
    --YOUR OTHER CONFIGS--
  ]
}

When this is configuration is added and your dev:debug script is running you are basically done with the setup. All that is left is to start the debugger in VS Code with our newly created Attach to Next Backend config. And you are good to go! Just add breaking points in your server side code and VSCode should stop at them when you run the debugger.

I hope this helps you get started with debugging your Next.js applications in VS Code.

Happy coding!