Missing source maps break client-side debugging under VSCode

[carlo-salinari]

Link to the code that reproduces this issue

https://github.com/carlo-salinari/debug-nextjs

To Reproduce

1. Start the application with npm run dev
2. In vscode, set a breakpoint at line 6 of page.tsx
3. Start a debugging session
4. Refresh page

Current vs. Expected behavior

Current behaviour:

• breakpoint goes gray (ignored)
• debug console say some source maps file are missing (see attachment) dbconsole.txt

Expected:

• hit the breakpoint and let you debug the app

Verify canary release

• [X] I verified that the issue exists in the latest Next.js canary release

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #34~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Sep  7 13:12:03 UTC 2
Binaries:
  Node: 19.4.0
  npm: 9.2.0
  Yarn: 1.22.19
  pnpm: 8.9.0
Relevant Packages:
  next: 13.5.5-canary.5
  eslint-config-next: 13.5.4
  react: 18.2.0
  react-dom: 18.2.0
  typescript: 5.2.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure

Additional context

No response

[Rishab49]

@carlo-salinari try replacing the content of .vscode/launch.json with following

{
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Next.js: debug server-side",
        "type": "node-terminal",
        "request": "launch",
        "command": "pnpm run 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": "pnpm run dev",
        "console": "integratedTerminal",
        "serverReadyAction": {
          "pattern": "started server on .+, url: (https?://.+)",
          "uriFormat": "%s",
          "action": "debugWithChrome"
        }
      }
    ]
  }

then, close all dev server and start debugging session in full stack mode

[carlo-salinari]

This was helpful, thanks.

Your launch.json has some invalid properties ("type": "pwa-chrome" and "console": "integratedTerminal"), but pointed me to the right direction.

Here's the one I ended up using (I've updated the reproduction repo):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach Chrome",
      "type": "chrome",
      "request": "attach",
      "port": 9222,
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

I adapted it from the official documentation (it's in the Pages Router section, there's no Debugging section in the App Router section).

"Next.js: debug full stack" works (but opens a new browser every time). Attaching to a running "use client" page in chrome doesn't seem to work (breakpoint is not hit).

At this point I don't even know if the problem is with nextjs, vscode or chrome.

[Rishab49]

@carlo-salinari maybe use client is not debuggable because it gets removed at compile time.

[jelling]

@carlo-salinari maybe use client is not debuggable because it gets removed at compile time.

At least in my case, that was the issue. Component A included Component B which used use client. As a result, Component A was no longer server-side debuggable.

I'm relatively new to Next.Js so I'm not certain if that is working as intended and it's just a matter of communicating this better. Or if this is a bug.

[heecheon92]

Mine got fixed by changing the pattern for serverReadyAction in launch.json

from

        "serverReadyAction": {
          "pattern": "started server on .+, url: (https?://.+)",
          "uriFormat": "%s",
          "action": "debugWithChrome"
        }

to

      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }

[prurph]

Has anyone figured out how to debug server-side by attaching to an already running process, instead of launching with node-terminal?

My issue is if I use a config like:

    {
      "type": "pwa-node",
      "name": "attach test",
      "request": "attach",
      "processId": "${command:PickProcess}",
      "cwd": "${workspaceFolder}"
    },

and then start NextJS with next dev (with or without NODE_OPTIONS='--inspect'), the debugger can attach, but breakpoints do not fire.

VSCode will say "breakpoint can't be set" and offers debugging help that seems to suggest source maps aren't being generated. Indeed, if I attach using chrome://inspect and hit CMD+P, node of my source files are listed, only node internals and node_module stuff. The docs say source maps are generated automatically in dev, so I'm not sure what is going on.

[Skarvion]

Seems that the discussion derailed from debugging client-side to server-side. I just fixed my client-side debugging issue today, and I find that the debugging documentation for TypeScript is lacking.

Solution

@carlo-salinari , I assume your issue is similar to mine, which is the problem on how to set up the sourceMapPathOverrides and sourceMaps.

The setup is dependent whether you use Turbopack or not.

Without Turbopack

Credit to this article although there's a typo with webRoot since it includes src in the path again. I've tweaked my code below to drop that.

{
  "name": "Next.js: debug client-side",
  "type": "msedge",
  "request": "launch",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}",
  "sourceMaps": true,
  "sourceMapPathOverrides": {
    "webpack://_N_E/*": "${webRoot}/*"
  }
}

With Turbopack

{
  "name": "Next.js: debug client-side",
  "type": "msedge",
  "request": "launch",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}",
  "sourceMaps": true,
  "sourceMapPathOverrides": {
    "/turbopack/[project]/*": "${webRoot}/*"
  }
}

How to diagnose the problem in the future

TLDR; use VSCode debug diagnostic to match the sourcemap path

I fixed the above problem by opening the devtool in the browser first and see the source tree first, to get a better feel of the TypeScript file structure

Then in VSCode, you open Debug Diagnostics (accessible via Command Palette). Select "What scripts and sourcemaps are loaded". Filter for the TSX file you're looking for, then you can grab the referenced from sourcemap to your launch.json

[carlo-salinari]

@Skarvion thanks for the hint. I don't use Turbopack yet. The Debug Diagnostics tool looks useful, but it is nowhere to be found in my VSCcode Command Palette (v1.85.2). Are you sure it is not from an Extension? Or maybe there is some intermediate step to activate it?

[Skarvion]

@carlo-salinari I just checked my environment, it comes from an extension called JavaScript Debugger. Apparently, it's a built-in extension, it should already be enabled for VSCode 1.46 onward. First time seeing a built-in extension, you can't even check it with @installed

Anyway, step by step:

1. Start Debugging (F5)
2. When you're in debug mode, open Debug Diagnostic through either:

• Open Command Palette and look for "Debug: Diagnose Breakpoint Problems". Only available when you're in debug mode
• Put a breakpoint somewhere and if it's greyed out, then if you hover your mouse, it offers more information and a button to troubleshoot

[Stan-Stani]

Fyi, my solution, where the client-side breakpoints just stopped working, was to close (and reopen) all my VSCode instances and then retry.

[porkopek]

Thank you very much, @carlo-salinari .

Now I got turbopack working with debugging, the lack of which prevented me to use it

For server and client side debugging, I just added

    { "name": "turbo",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run turbo",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      },
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      }
    }

where `npm run turbo` is `  an script like: "turbo": "next dev --turbo",`

[andrewmartin]

Hi everyone, thanks for your help and digging into this––

Curious if y'all have had any luck with getting server side files to work, cross-posting from https://github.com/vercel/next.js/issues/62008#issuecomment-1944338999

[DrPye]

@andrewmartin

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev --turbo"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev --turbo",
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "/turbopack/[project]/*": "${webRoot}/*"
      },
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}