Debugging

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.

Create a file named at the root of your project with the following content:

npm run dev can be replaced with yarn dev if you’re using Yarn. If you’re changing the port number your application starts on, replace the 3000 in http://localhost:3000 with the port you’re using instead.

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.

Start your development server as usual by running next dev, npm run dev, or . Once the server starts, open http://localhost:3000 (or your alternate URL) in Chrome. Next, open Chrome’s Developer Tools (Ctrl+Shift+J on Windows/Linux, ⌥+⌘+I on macOS), then go to the Sources tab.

Now, any time your client-side code reaches a debugger statement, code execution will pause and that file will appear in the debug area. You can also press Ctrl+P on Windows/Linux or ⌘+P on macOS to search for a file and set breakpoints manually. Note that when searching here, your source files will have paths starting with webpack://_N_E/./.

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

If you’re using npm run dev or yarn dev (see ) then you should update the dev script on your package.json:

Once the server starts, open a new tab in Chrome and visit , where you should see your Next.js application inside the Remote Target section. Click inspect under your application to open a separate DevTools window, then go to the Sources tab.

Debugging server-side code here works much like debugging client-side code with Chrome DevTools, except that when you search for files here with Ctrl+P or ⌘+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).

Windows users may run into an issue when using NODE_OPTIONS='--inspect' as that syntax is not supported on Windows platforms. To get around this, install the package as a development dependency (-D with npm and yarn) and replace the dev script with the following.

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