Next.js supports full source maps for both frontend and backend code. This guide covers debugging with VS Code, browser DevTools, and JetBrains WebStorm.
VS Code
Create a .vscode/launch.json file at the project root:
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: debug server-side",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev -- --inspect"
},
{
"name": "Next.js: debug client-side",
"type": "chrome",
"request": "launch",
"url": "http://localhost:3000"
},
{
"name": "Next.js: debug client-side (Firefox)",
"type": "firefox",
"request": "launch",
"url": "http://localhost:3000",
"reAttach": true,
"pathMappings": [
{
"url": "webpack://_N_E",
"path": "${workspaceFolder}"
}
]
},
{
"name": "Next.js: debug full stack",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/node_modules/next/dist/bin/next",
"runtimeArgs": ["--inspect"],
"skipFiles": ["<node_internals>/**"],
"serverReadyAction": {
"action": "debugWithEdge",
"killOnServerStop": true,
"pattern": "- Local:.+(https?://.+)",
"uriFormat": "%s",
"webRoot": "${workspaceFolder}"
}
}
]
}
- For Firefox debugging, install the Firefox Debugger extension.
- For the full-stack config, change
debugWithEdge to debugWithChrome if you use Chrome.
- If using a Turborepo, add
"cwd": "${workspaceFolder}/apps/web" to server-side and full-stack configurations.
- Replace
3000 with your custom port if needed.
Ctrl+Shift+D / ⇧+⌘+D), select a configuration, and press F5 to start debugging.
JetBrains WebStorm
- Click the run configuration dropdown and select Edit Configurations
- Create a JavaScript Debug configuration with
http://localhost:3000 as the URL
- Run the configuration—the browser opens automatically and both the Node.js and browser processes are in debug mode
Client-side code
Start the dev server (next dev) and open http://localhost:3000 in your browser.
- Open DevTools (
Ctrl+Shift+J / ⌥+⌘+I)
- Go to the Sources tab
- Search for files with
Ctrl+P / ⌘+P
Source files have paths starting with webpack://_N_E/./.
- Open DevTools (
Ctrl+Shift+I / ⌥+⌘+I)
- Go to the Debugger tab
- Search with
Ctrl+P / ⌘+P or use the file tree
Source files have paths starting with webpack://_N_E/./.debugger statements, or you can set breakpoints manually by clicking line numbers in the Sources panel.
Install the React Developer Tools browser extension for React-specific debugging:
- Inspect component trees
- View and edit props and state
- Identify performance issues
Server-side code
Pass the --inspect flag to attach the Node.js inspector:
The terminal output confirms the debugger is listening:
Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
- Open a new tab and navigate to
chrome://inspect
- Find your Next.js app in the Remote Target section
- Click inspect to open DevTools
- Go to the Sources tab
Server source files have paths starting with webpack://{application-name}/./.
- Navigate to
about:debugging
- Click This Firefox in the sidebar
- Find your Next.js app under Remote Targets
- Click Inspect and go to the Debugger tab
Use --inspect=0.0.0.0 to allow remote debugging from outside localhost, such as when running in a Docker container.
Inspect server errors in the browser
When an error occurs, click the Node.js icon on the error overlay (below the Next.js version indicator). This copies the DevTools URL to your clipboard, which you can open in a new tab to inspect the server process.
Source maps
Next.js generates source maps for both client and server code during development. In production, source maps are not generated by default, but can be enabled:
module.exports = {
productionBrowserSourceMaps: true,
}
Windows note
If you see slow Fast Refresh on Windows, disable Windows Defender real-time protection for your project directory. This is a known external issue that affects file-read performance. 
