How to use debugging tools with Next.js

This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using theVS Code debugger,Chrome DevTools, orFirefox DevTools.

Any debugger that can attach to Node.js can also be used to debug a Next.js application. You can find more details in the Node.jsDebugging Guide.

Debugging with VS Code

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

Note: To use Firefox debugging in VS Code, you'll need to install theFirefox Debugger extension.

npm run dev can be replaced withyarn dev if you're using Yarn orpnpm dev if you're using pnpm.

In the "Next.js: debug full stack" configuration,serverReadyAction.action specifies which browser to open when the server is ready.debugWithEdge means to launch the Edge browser. If you are using Chrome, change this value todebugWithChrome.

If you'rechanging the port number your application starts on, replace the3000 inhttp://localhost:3000 with the port you're using instead.

If you're running Next.js from a directory other than root (for example, if you're using Turborepo) then you need to addcwd to the server-side and full stack debugging tasks. For example,"cwd": "${workspaceFolder}/apps/web".

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

Using the Debugger in Jetbrains WebStorm

Click the drop down menu listing the runtime configuration, and clickEdit Configurations.... Create aJavaScript Debug debug configuration withhttp://localhost:3000 as the URL. Customize to your liking (e.g. Browser for debugging, store as project file), and clickOK. Run this debug configuration, and the selected browser should automatically open. At this point, you should have 2 applications in debug mode: the NextJS node application, and the client/browser application.

Debugging with Browser DevTools

Client-side code

Start your development server as usual by runningnext dev,npm run dev, oryarn dev. Once the server starts, openhttp://localhost:3000 (or your alternate URL) in your preferred browser.

For Chrome:

• Open Chrome's Developer Tools (Ctrl+Shift+J on Windows/Linux,⌥+⌘+I on macOS)
• Go to theSources tab

For Firefox:

• Open Firefox's Developer Tools (Ctrl+Shift+I on Windows/Linux,⌥+⌘+I on macOS)
• Go to theDebugger tab

In either browser, any time your client-side code reaches adebugger statement, code execution will pause and that file will appear in the debug area. You can also search for files to set breakpoints manually:

• In Chrome: PressCtrl+P on Windows/Linux or⌘+P on macOS
• In Firefox: PressCtrl+P on Windows/Linux or⌘+P on macOS, or use the file tree in the left panel

Note that when searching, your source files will have paths starting withwebpack://_N_E/./.

React Developer Tools

For React-specific debugging, install theReact Developer Tools browser extension. This essential tool helps you:

• Inspect React components
• Edit props and state
• Identify performance problems

Server-side code

To debug server-side Next.js code with browser DevTools, you need to pass the--inspect flag:

nextdev--inspect

The value of--inspect is passed to the underlying Node.js process. Check out the--inspect docs for advanced use cases.

Good to know: Use--inspect=0.0.0.0 to allow remote debugging access outside localhost, such as when running the app in a Docker container.

Launching the Next.js dev server with the--inspect flag will look something like this:

Debuggerlisteningonws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95Forhelp,see:https://nodejs.org/en/docs/inspectorready-startedserveron0.0.0.0:3000,url:http://localhost:3000

For Chrome:

1. Open a new tab and visitchrome://inspect
2. Look for your Next.js application in theRemote Target section
3. Clickinspect to open a separate DevTools window
4. Go to theSources tab

For Firefox:

1. Open a new tab and visitabout:debugging
2. ClickThis Firefox in the left sidebar
3. UnderRemote Targets, find your Next.js application
4. ClickInspect to open the debugger
5. Go to theDebugger tab

Debugging server-side code works similarly to client-side debugging. When searching for files (Ctrl+P/⌘+P), your source files will have paths starting withwebpack://{application-name}/./ (where{application-name} will be replaced with the name of your application according to yourpackage.json file).

To use--inspect-brk or--inspect-wait, you have to specifyNODE_OPTIONS instead. e.g.NODE_OPTIONS=--inspect-brk next dev.

Inspect Server Errors with Browser DevTools

When you encounter an error, inspecting the source code can help trace the root cause of errors.

Next.js will display a Node.js icon underneath the Next.js version indicator on the error overlay. By clicking that icon, the DevTools URL is copied to your clipboard. You can open a new browser tab with that URL to inspect the Next.js server process.

Debugging on Windows

Ensure Windows Defender is disabled on your machine. This external service will checkevery file read, which has been reported to greatly increase Fast Refresh time withnext dev. This is a known issue, not related to Next.js, but it does affect Next.js development.

More information

To learn more about how to use a JavaScript debugger, take a look at the following documentation:

• Node.js debugging in VS Code: Breakpoints
• Chrome DevTools: Debug JavaScript
• Firefox DevTools: Debugger