180 lines
8.2 KiB
Markdown
180 lines
8.2 KiB
Markdown
|
---
|
||
|
|
title: How to use debugging tools with Next.js
|
||
|
|
nav_title: Debugging
|
||
|
|
description: Learn how to debug your Next.js application with VS Code, Chrome DevTools, or Firefox DevTools.
|
||
|
|
---
|
||
|
|
|
||
|
|
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||
|
|
|
||
|
|
This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using the [VS Code debugger](https://code.visualstudio.com/docs/editor/debugging), [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools), or [Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/).
|
||
|
|
|
||
|
|
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.js [Debugging Guide](https://nodejs.org/en/docs/guides/debugging-getting-started/).
|
||
|
|
|
||
|
|
## Debugging with VS Code
|
||
|
|
|
||
|
|
Create a file named `.vscode/launch.json` at the root of your project with the following content:
|
||
|
|
|
||
|
|
```json filename="launch.json"
|
||
|
|
{
|
||
|
|
"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 the [Firefox Debugger extension](https://marketplace.visualstudio.com/items?itemName=firefox-devtools.vscode-firefox-debug).
|
||
|
|
|
||
|
|
`npm run dev` can be replaced with `yarn dev` if you're using Yarn or `pnpm 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 to `debugWithChrome`.
|
||
|
|
|
||
|
|
If you're [changing the port number](/docs/pages/api-reference/cli/next#next-dev-options) your application starts on, replace the `3000` in `http://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 add `cwd` 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 press `F5` or select **Debug: 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 click `Edit Configurations...`. Create a `JavaScript Debug` debug configuration with `http://localhost:3000` as the URL. Customize to your liking (e.g. Browser for debugging, store as project file), and click `OK`. 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 running `next dev`, `npm run dev`, or `yarn dev`. Once the server starts, open `http://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 the **Sources** tab
|
||
|
|
|
||
|
|
For Firefox:
|
||
|
|
|
||
|
|
- Open Firefox's Developer Tools (`Ctrl+Shift+I` on Windows/Linux, `⌥+⌘+I` on macOS)
|
||
|
|
- Go to the **Debugger** tab
|
||
|
|
|
||
|
|
In either browser, any time your client-side code reaches a [`debugger`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/debugger) 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: Press `Ctrl+P` on Windows/Linux or `⌘+P` on macOS
|
||
|
|
- In Firefox: Press `Ctrl+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 with `webpack://_N_E/./`.
|
||
|
|
|
||
|
|
### React Developer Tools
|
||
|
|
|
||
|
|
For React-specific debugging, install the [React Developer Tools](https://react.dev/learn/react-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:
|
||
|
|
|
||
|
|
```bash package="pnpm"
|
||
|
|
pnpm dev --inspect
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash package="npm"
|
||
|
|
npm run dev -- --inspect
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash package="yarn"
|
||
|
|
yarn dev --inspect
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash package="bun"
|
||
|
|
bun run dev --inspect
|
||
|
|
```
|
||
|
|
|
||
|
|
The value of `--inspect` is passed to the underlying Node.js process. Check out the [`--inspect` docs for advanced use cases](https://nodejs.org/api/cli.html#--inspecthostport).
|
||
|
|
|
||
|
|
> **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 server with the `--inspect` flag will look something like this:
|
||
|
|
|
||
|
|
```bash filename="Terminal"
|
||
|
|
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
|
||
|
|
```
|
||
|
|
|
||
|
|
For Chrome:
|
||
|
|
|
||
|
|
1. Open a new tab and visit `chrome://inspect`
|
||
|
|
1. Look for your Next.js application in the **Remote Target** section
|
||
|
|
1. Click **inspect** to open a separate DevTools window
|
||
|
|
1. Go to the **Sources** tab
|
||
|
|
|
||
|
|
For Firefox:
|
||
|
|
|
||
|
|
1. Open a new tab and visit `about:debugging`
|
||
|
|
1. Click **This Firefox** in the left sidebar
|
||
|
|
1. Under **Remote Targets**, find your Next.js application
|
||
|
|
1. Click **Inspect** to open the debugger
|
||
|
|
1. Go to the **Debugger** 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 with `webpack://{application-name}/./` (where `{application-name}` will be replaced with the name of your application according to your `package.json` file).
|
||
|
|
|
||
|
|
To use `--inspect-brk` or `--inspect-wait`, you have to specify `NODE_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 check _every file read_, which has been reported to greatly increase Fast Refresh time with `next 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](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_breakpoints)
|
||
|
|
- [Chrome DevTools: Debug JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript)
|
||
|
|
- [Firefox DevTools: Debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/)
|