next.js: Missing source maps break client-side debugging under VSCode

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

  • 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

About this issue

Most upvoted comments

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

image

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

image

@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}"
      }
    }
  ]
}

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",`