NextJS is the hot JavaScript framework right now, and like all JavaScript, it can cause quite a few bugs on both the client- and server-side of your applications.

NextJS is so hot right now
NextJS is so hot right now

One of the most powerful features of NextJS is enabling you to use your code, templates, and patterns across both the server and the client. NextJS will mostly figure out the most efficient place to run. This is super powerful and makes NextJS applications feel very fast compared to strictly client-side rendered applications.

However, that does mean you need to handle errors and exceptions in both the client-side browser environment as well as the NodeJS server. There are two slightly different ways to make sure you monitor all the ways your NextJS application can fail.

Client-Side Error Handling in NextJS

NextJS is built on top of React and utilizes the ErrorBoundary concept to handle errors at different levels of the application. This could be useful if you want to have different error screens for different parts of the app.

Of course, we can’t predict where errors will occur, so we also need a “top level” error handler to catch everything. This is also the best place to plug in an error monitoring service like TrackJS. In NextJS, the top-level error handler is the global-error.tsx file in the root of app.

"use client";

import NextError from "next/error";
import { useEffect } from "react";
import { TrackJS } from "trackjs";

// Setup your error monitoring
TrackJS.install({...});

export default function GlobalError({ error, reset }) {

  useEffect(() => {
    // Capture an error
    TrackJS.track(error);
  }, [error]);

  return (
    <html>
      <body>
        {/* This is the default Next.js error component. */}
        <NextError statusCode={undefined as any} />
      </body>
    </html>
  );
}
NextJS global-error.tsx

The global-error.tsx file only runs in the client-side environment, so it needs to start with the NextJS "use client" directive.


Quick aside, the TrackJS agent has been using the custom "use awesome" directive for over 10 years now. Because, ya know, it’s awesome.


Most of this global-error.tsx is the standard boilerplate, with 2 additions: first, the call to TrackJS.install. This is where you can configure your instrumentation of the client-side to gather any additional context for your errors. This code will be run right away, regardless of whether or not an error occurs.

The other addition is the call to TrackJS.track within the useEffect. This get’s called by NextJS when an error actually has occurred in a production environment. Even if your error monitoring automatically captures errors (like TrackJS), sending the errors directly within the useEffect will provide better error data.

Don’t Forget! The global-error.tsx only runs in production builds. To test out your error handling, you need to build and start the project in production mode.

Server-Side Error Handling in NextJS

Some of your application code will also be run on the NodeJS server-side of NextJS. NextJS does a pretty good job of detecting most failures, and when it does, it routes the errors to the client-side where it will be recorded by the global-error.tsx file.

But it doesn’t catch everything.

There are several situations where NextJS can blow up on the server and not return anything to the client. How can you detect when those errors happen?

There is no app.tsx or other root application file to plug into. However, the root layout.tsx file is one of the first things that runs on both client and server, so it’s a great place to add other application-level configuration and calls.

import type { Metadata } from "next";
import { TrackJS } from "trackjs-node";

// Setup your error monitoring
TrackJS.install({...});

export const metadata: Metadata = {...};

export default function RootLayout({ children }: Readonly) {
  return (/*your layout markup*/);
}
NextJS layout.tsx

Your layout.tsx file will look much more complicated as it will have lots of general structure and layout for your application. But where I have the call to TrackJS.install is a great place to set up general error handling that will run on the server. An error monitoring system like TrackJS will attach itself to all the places a NodeJS application can fail and record errors automatically.

Note On the server-side, we use a trackjs-node package instead of the standard browser agent. You probably want to implement an isomorphic wrapper around both agents to centralize your configuration, which is very easy to do.

Build NextJS Apps with Confidence!

Bugs are inevitable, even in modern frameworks. Having a system to automatically capture and report errors when they happen is key to having confidence in your development cycle, and your products.

TrackJS error monitoring fully supports NextJS, and all other JavaScript technologies. Built by developers for developers.

Did you like this?
CEO TrackJS
Todd is a software engineer, business leader, and developer advocate with 20+ years of experience. He is a co-founder and CEO of TrackJS and Request Metrics,...

What to do Next:

1. Try TrackJS on Your Website

TrackJS gives you the visibility to find and fix your errors before users find them. Get started in 5 minutes tracking errors with all the context you'll need to squash the important bugs in your app.

2. Get the Debugger Newsletter

Join The Debugger for amazing JavaScript tips, debugging walkthroughs, news, and product releases for Request Metrics. No more than once a week, probably a lot less.