How to debug Next.js applications with VS Code

Debugging Next.js is hard. Their documentation includes a Debugging page, but as of this writing, it only covers debugging server-side code. The worst part, though, is that it doesn’t say it only works for server-side code, which caused me a good deal of frustration (and nearly tears) wondering why none of my breakpoints were working. My current project, as it happens, is completely statically generated so far, so all of my code is client-side.

There’s been an open issue in the Next.js repo for over a year now on this subject. That led me in the right direction, at least: to some relatively new magic in VS Code’s built-in JavaScript debugger and a closer look at the editor’s debugging docs. After all this investigation, I’ve come up with a few launch configurations that have solved all my Next.js debugging problems, letting me debug just the front end, just the back end, or both at the same time, right in the comfort of VS Code. I hope they can help you too!

To get started, create a file named .vscode/launch.json at the root of your project with the following content:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "next dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "pwa-chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "next dev",
      "console": "integratedTerminal",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

If you’re using npm run dev or yarn dev to start your dev server, replace both instances of next dev above with npm run dev or yarn dev, whichever you’re using. If you’re changing the port number your application starts on, replace the 3000 in http://localhost:3000 with the port you’re using instead.

Now go to the Debug panel (Ctrl+Shift+D on Windows/Linux, ⇧⌘D on macOS), select a launch configuration, then press F5 or select Debug: Start Debugging from the Command Palette to start your debugging session. Voilà!

I’ve opened a Next.js documentation PR with these improvements, so hopefully their debugging page won’t be out of date for too much longer. 🤞🏼 Update: The PR has merged! Now I’ll see about adding these launch configs to create-next-app.