Guides & SDKsAPI Reference
Guides & SDKs
Log InSign Up

Next.js

Error reporting with Rollbar and Next.js | Support Level: Supported

Suggest Edits

Overview

Rollbar supports both the pages and app routing versions of Next.js.
While there are some difference in the usage between the two, the setup
remains the same.

Pre-requisites

  • Next.js (both pages and app routing is supported)
  • Rollbar account
    • Client-side access token
    • Server-side access token

Installation

# npm
> npm install rollbar @rollbar/react

# yarn
> yarn add rollbar @rollbar/react

# pnpm
> pnpm add rollbar @rollbar/react

Configuration

Add your access tokens

You can add your Rollbar access tokens as environment variables. To get started add the following environment variables to the correct .env for your environment:

NEXT_PUBLIC_ROLLBAR_CLIENT_TOKEN=<POST CLIENT ITEM TOKEN>
ROLLBAR_SERVER_TOKEN=<POST SERVER ITEM TOKEN>

These tokens can be found on your project access tokens page. Take care to not put an access token with the Post Server Item scope in an environment variable that is prefixed with NEXT_PUBLIC as those will be compiled into the code that is delivered to your client side JS.

Configure Rollbar

We suggest you create a single instance for use server side, to be certain there are not more than one, and a config to use in your client side components. React Server Components limit you to passing simple objects as props from Server Components to Client Components, so using a simple serializable object will work regardless if you are using the app/ or pages/ routers. 

/// ./src/rollbar.js
import Rollbar from 'rollbar';

const baseConfig = {
  captureUncaught: true,
  captureUnhandledRejections: true,
  environment: process.env.NODE_ENV,
};

export const clientConfig = {
  accessToken: process.env.NEXT_PUBLIC_ROLLBAR_CLIENT_TOKEN,
  ...baseConfig,
};

export const serverInstance = new Rollbar({
  accessToken: process.env.ROLLBAR_SERVER_TOKEN,
  ...baseConfig,
});

Usage

App Router

💡

Example project: Rollbar React - Next.js (App Router)

Configure the Rollbar Provider

To be able to use the hooks consistently through your application. It is easiest if you configure your Rollbar Provider within your root layout.

/// ./src/app/layout.js
import { Provider as RollbarProvider } from '@rollbar/react';
import { clientConfig } from '@/rollbar';

...

export default function RootLayout(children) {
  return (
    <RollbarProvider config={clientConfig}>
      <html lang="en">
        <body>{children}</body>
      </html>
    </RollbarProvider>
  );
 }

Note: The Rollbar Provider uses a React Context. This context, like hooks are only available for use in your client components.

Using the Next.js Route Error Handler (recommended)

Next.js provides an error handler this handler will automatically wrap your router, at the desired level, within an Error Boundary. It is recommended to use your Rollbar instance within this error handler to report errors to Rollbar.

Creating an error.js/tsx file in the root of your app/ folder will catch any errors created within the rest of your pages. You can also specific an error handler specific to a given page within its own folder. For errors in your global layout and template see the next section.

'use client'; // Error components must be Client Components

import { useEffect } from 'react';
import { ResetPage } from '@/components/ResetPage';
import { useRollbar } from '@rollbar/react';

export default function Error({
  error,
  reset,
}) {
  const rollbar = useRollbar();
  useEffect(() => {
    rollbar.error(error);
  }, [error, rollbar]);

  return <ResetPage reset={reset} />;
}

Catching errors in your root layout or template

Errors generated within your root layout and template are note handled by the top level error.js/tsx file. Instead you need to create a global-error.js/tsx. This handler will catch errors, including from your root layout and relay then to Rollbar.

/// ./src/app/global-error.js
'use client';

import { useEffect } from 'react';
import Rollbar from 'rollbar';
import { clientConfig } from '@/rollbar';
import { ResetPage } from '@/components/ResetPage';

export default function GlobalError({
  error,
  reset,
}) {
  useEffect(() => {
    // Root layout and template are not available in the error page
    // so we don't have the RollbarProvider available to use the
    // useRollbar hook so we need to create a new Rollbar instance here
    const rollbar = new Rollbar(clientConfig);
    
    rollbar.error(error);
  }, [error]);

  return (
    <html>
      <body>
        <ResetPage reset={reset} />;
      </body>
    </html>
  );
}

Using the Rollbar React ErrorBoundary

The <ErrorBoundary> component provided by the @rollbar/react library may still be used if you would prefer that over the built in Next.js error handler.

'use client';

import { ErrorBoundary } from '@rollbar/react';

import { ResetPage } from '@/components/ResetPage';

export default function RollbarErrorBoundary() {
  return (
    <ErrorBoundary fallbackUI={() => <ResetPage reset={() => { location.reload()}} />}>
      <button
        className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
        onClick={() => {
          throw new Error('Something broke');
        }}
      >
        Click for Error with Rollbar Error Boundary
      </button>
    </ErrorBoundary>
  );
}

Pages Router

💡

Example project: Rollbar React - Next.js (Pages Router)

Add Rollbar to your Custom App

The first step in using Rollbar within the pages directory is wrapping your application with a Rollbar <Provider/> and <ErrorBoundary/>.

/// ./src/pages/_app.js
import "@/styles/globals.css";
import type { AppProps } from "next/app";
import { Provider, ErrorBoundary } from '@rollbar/react';

import { clientConfig } from '@/rollbar';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Provider config={clientConfig}>
      <ErrorBoundary
        level="critical"
        errorMessage="example error boundary message"
        fallbackUI={() => (
          <p style={{ color: 'red' }}>Oops, there was an error.</p>
        )}
        extra={{ more: 'data' }}
        callback={() => console.log('an exception was sent to rollbar')}
      >
        <Component {...pageProps} />
      </ErrorBoundary>
    </Provider>
  );;
}

This setup will ensure that all* (see Notes below) errors within your application are captured, and reported, and ensures that Rollbar is always available to use within lower components you may want to handle errors within also.

Catching errors within another Component

Sometimes you want to capture errors within a more limited part of your application and show a specific error for that area of your UI. This can be accomplished by wrapping that component in an <ErrorBoundary />

/// ./SomeComponent.js
import { ErrorBoundary } from '@rollbar/react';

import { ResetPage } from '@/components/ResetPage';

export default function SomeComponent() {
  return (
    <ErrorBoundary fallbackUI={() => <ResetPage reset={() => {}} />}>
      <button
        onClick={() => {
          throw new Error('Something broke');
        }}
      >
        Click for Error with Rollbar Error Boundary
      </button>
    </ErrorBoundary>
  );
}

Notes

  • By default Next.js will automatically catch errors when running the dev server. To properly test Rollbar you will need to do build and run the server directly
  • The ErrorBoundary class is not perfect at catching and stopping the propagation of all errors, particularly async errors. Be aware, that if you turn on captureUncaught or captureUnhandledRejections in your Rollbar config you may receive doubled occurrences.
  • Further details on usage of Rollbar React can be found within it’s README.

📘Thanks

Many thanks to Max Schmitt, for the blog post and content for using Rollbar with Next.js from which provided our original documentation.

Original Blog Post: https://maxschmitt.me/posts/error-reporting-rollbar-nextjs/

Updated about 2 months ago