Next.js: Request for documentation using breakpoint/debugging

[stoplion]

Hi,
Would like to request for documentation using breakpoint/debugging.
Seems some of the recommended ways on the internets are out of date now (on Spectrum / SO, etc..).
Some documentation from Zeit would be awesome..

[borekb]

Just going to add a couple of notes from my experience as of Next.js 9.0.3.

Server-side

✅ This config in .vscode/launch.json works for me:

{
  "type": "node",
  "request": "launch",
  "name": "Next.js server-side",
  "runtimeExecutable": "node",
  "runtimeArgs": ["--inspect", "node_modules/.bin/next", "dev"],
  "port": 9229
}

I can then do this in VSCode:

1. Place breakpoints in pages/_app.tsx, both in getInitialProps and in render.
2. Place breakpoints in pages/some-other-page.tsx, both in getInitialProps and in render.
3. Start the debug session.
4. Navigate to various pages in the browser and see the breakpoints hit after a full reload (which is necessary to trigger SSR).

Note how our code is in TypeScript but I didn't need to add -r ts-node/register or similar.

If I had the next binary installed globally, this should also work (note the NODE_OPTIONS approach):

{
  "type": "node",
  "request": "launch",
  "name": "Global next binary",
  "runtimeExecutable": "next",
  "runtimeArgs": ["dev"],
  "env": {
    "NODE_OPTIONS": "--inspect"
  },
  "port": 9229
},

But I haven't tried as we have Next.js as a devDependency.

🚫 A method that doesn't work for me (but I generally like it) is having something like this in package.json:

{
  "scripts": {
    "dev": "next dev",
    "dev:debug": "node --inspect node_modules/.bin/next dev"
  }
}

Then run yarn dev:debug it iTerm or similar and launch a "Node: Attach" config:

{
  "type": "node",
  "request": "attach",
  "name": "Node attach",
  "port": 9229
}

This works for our plain Node.js projects but in a Next.js app, even though VSCode seemingly connects to the debugger (the status bar goes orange, the Debug Console mirrors console output, etc.), my breakpoints are not hit. I'm almost sure that it has something to do with the process being started through yarn and not directly. If anyone knows how to fix this, I'd be interested.

✅ A workaround for this is, of course, to run the command directly:

node --inspect node_modules/.bin/next dev

(or --inspect-brk).

Client-side

✅ If I don't need the familiarity and comfort of VSCode, by far the easiest is to just debug in Chrome directly. In DevTools, I go to Sources panel, press the familiar Cmd+P, browse to a file like webpack://./pages/_app.tsx (yes, it's TypeScript directly) and set breakpoints there.

✅ Debugging via VSCode works as well but there's a bit of a setup. After installing this VSCode extension, the most annoying part is starting Chrome with remote debugging on, which on a Mac is done from the command line:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

For this to work, Chrome must be shut down entirely or otherwise, the existing instance will be used, without the debugger. (I use Chrome Canary for development so that I don't need to mess with my main Chrome browser but still, it's inconvenient.)

When the setup is done, this launch config is enough to connect VSCode to Chrome:

{
  "type": "chrome",
  "request": "attach",
  "name": "Chrome attach",
  "port": 9222
}

It's also possible to launch Chrome directly:

{
  "type": "chrome",
  "request": "launch",
  "name": "Launch Chrome",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}"
}

Compound configuration

It's possible to run both server-side and client-side debugging in VSCode using a compound configuration, for example:

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Next.js server-side",
      // etc.
    },
    {
      "type": "chrome",
      "request": "attach",
      "name": "Next.js client-side",
      // etc.
    }
  ],
  "compounds": [
    {
      "name": "Next.js full-stack",
      "configurations": ["Next.js server-side", "Next.js client-side"]
    }
  ]
}

Custom server

With Next.js 9 dynamic routing, we no longer have a reason to use a custom server but previously, we had a config like this:

{
  "type": "node",
  "request": "launch",
  "name": "Next.js custom server",
  "runtimeArgs": ["-r", "ts-node/register", "--inspect", "server/server.ts"],
  "env": {
    "TS_NODE_PROJECT": "tsconfig.server.json"
  },
  "port": 9229,
  "stopOnEntry": false
}

We also had a dev:debug script in package.json that looked like this:

{
  "scripts": {
    "dev:debug": "NODE_ENV=development TS_NODE_PROJECT=tsconfig.server.json node -r ts-node/register --inspect server/server.ts",
  }
}

I'm pretty sure it worked fine with the _Node attach_ configuration. Overall, custom server was not a problem. ✅

Issues I know about

• Debugging doesn't work on dynamic page components like pages/post/[id].js: #8295

Resources

• Official docs mentioning --inspect
• VSCode recipe for Next.js debugging

[lavaxun]

Thanks for the guide. the server-side debugging seems working.
However the client-side debugging is not.

I tried the above configuration (both attach and launch mode) but breakpoints are still greyed out.

Anyone else facing the same issue as me?

[borekb]

@lavaxun Does it work when you debug directly in Chrome?

[vvo]

Hey there, I just used Chrome DevTools to debug a Next.js app, here's how: https://github.com/zeit/next.js/pull/10807m, let me know!

[sc0ttdav3y]

I think clearer documentation for server-side debugging would be useful on https://nextjs.org/docs/api-reference/cli.

Its current suggestion is to run NODE_OPTIONS='--inspect' next. That may work on as a standalone command, however if you bake that into package.json and also use typescript, then you get the dreaded "address already in use" bug (https://github.com/zeit/next.js/issues/9027). And the solution is not entirely obvious.

I'd like to suggest the documentation provide a boilerplate package.json with server-side debugging included. This works for me:

{
  "scripts": {
    "debug": "node --inspect node_modules/.bin/next dev",
  }
}