Next.js Debugging

Next.js is more difficult to debug than a conventional browser-only React app since it is a React meta-framework that runs in both Node.js and the browser.

We’ll go over a few different debugging techniques, each of which has its own set of applications.


The classic technique that you can use to verify if and when a piece of code is executing, and log any values you’re interested in.


let theme = props.theme;

// Basic usage
console.log('theme', theme);

// Indented JSON output with 2 spaces
console.log('theme', JSON.stringify(theme, undefined, 2));

// Human-readable output with colors
console.log('theme', require('util').inspect(theme, { colors: true }))

Using JSON.stringify or require(‘util’).inspect can be useful to control the format of your logged values, for enhanced readability.

Step-by-step debugging

Using a step-through debugger to pause and inspect your code while it executes is often more beneficial. This is especially true in the following situations:

  • You have a complicated control flow and/or a large number of variables, making it difficult to put terminal statements everywhere.
  • By examining up and down the call stack, you can figure out how a function is called.
  • You’re unsure which values or functions you’d like to examine before launching your app.

Browser-only debugging

Simply use the following command to debug your Next.js app in the browser:

  • Start your app in “dev” mode using the following command:

npm run dev

  • In your browser, open your app and then open chrome developer tools.
  • To set a breakpoint, go to the “Sources” tab and click on a line number.

You may use the JS console to run code, browse the call stack, and step through your code from here.

Source maps

In dev mode, Next.js has source maps enabled by default, so you can see your uncompiled source code and browse to a specific source file using the sidebar or the “Go to source” shortcut: Cmd+P on MacOS.

However, there are situations when you’re debugging compiled code and the source code doesn’t provide enough information to figure out what’s going on. You wish to run util.inspect, for example, but util isn’t a run-time name:

Fortunately, you can turn off source maps and see the generated code that’s actually running. Uncheck “Enable JavaScript source maps” in Chromium-based browsers’ DevTools settings:

Then it becomes evident that the module was renamed by webpack at runtime:

Server-only debugging

The browser is only half the story with Next.js apps. By default, the app is rendered on the server before being sent to the browser.

Some of this code is executed only on the server, so it’s not possible to debug it in the browser at all, e.g. getServerSideProps, getStaticProps, and getStaticPaths.

The Next.js server is fundamentally a Node.js process, so it can be debugged like any other Node.js process.

Node.js built-in debugger

The built-in debugger is probably the easiest to launch. First add a debugger; statement somewhere in your code, then:

node inspect ./node_modules/next/dist/bin/next

Use commands like cont (shortcut c) to continue execution, exec() to evaluate an expression, or next (shortcut n) to step to the next line.

In situations where you only have command line access to the app you’re debugging, the built-in debugger may be your only option.


Leave a Reply

Your email address will not be published. Required fields are marked *