Next.js integration guide

Typical installation time: 7 minutes

Hi there! You’ve found Honeybadger’s guide to Next.js error and exception tracking. Once installed, Honeybadger will automatically report errors from your Next.js application.

The @honeybadger-io/nextjs package utilizes the packages @honeybadger-io/js, @honeybadger-io/react and @honeybadger-io/webpack under the hood to provide a simplified integration package for Next.js applications. You can always refer to these packages’ documentation for more information and advanced configuration.

Features

• App Router support (added with Next.js 13)
• Automatic reporting of uncaught exceptions (see Limitations)
• Breadcrumbs
• Source map upload to Honeybadger
• CLI command to generate Honeybadger configuration files for Next.js runtimes

Installation

Add @honeybadger-io/nextjs and @honeybadger-io/react as dependencies.

# npm
npm add @honeybadger-io/react @honeybadger-io/nextjs --save

# yarn
yarn add @honeybadger-io/react @honeybadger-io/nextjs

Configuration

Note

Honeybadger needs a configuration file for each Next.js runtime. Additionally, some more configuration in next.config.js is required to setup the runtime and upload source maps to Honeybadger. Even though you can configure each file separately, we recommend to use Honeybadger’s environment variables to set configuration values once: NEXT_PUBLIC_HONEYBADGER_API_KEY (Honeybadger API key), NEXT_PUBLIC_HONEYBADGER_REVISION (Revision of current deployment) and NEXT_PUBLIC_HONEYBADGER_ASSETS_URL (URL to your public assets).

Run the following command, which generates configuration files in your project root for each Next.js runtime:

npx honeybadger-copy-config-files

The following files will added to your project:

• honeybadger.server.config.js - Configuration file for Next.js server runtime
• honeybadger.client.config.js - Configuration file for Next.js client runtime
• honeybadger.edge.config.js - Configuration file for Next.js Edge runtime
• pages/_error.[js|tsx] - Next.js Pages Router custom error component - if pages folder exists
• app/error.[js|tsx] - Next.js App Router custom error component - if app folder exists
• app/global-error.[js|tsx] - Next.js App Router global error component - if app folder exists

Note: The honeybadger.edge.config.js file is necessary if you deploy your Next.js application to Vercel and use Vercel Edge Functions. If not, you can safely remove this file.

Note: The script will create backups of any existing files.

In your next.config.js:

const { setupHoneybadger } = require("@honeybadger-io/nextjs");

const moduleExports = {
  // ... Your existing module.exports object goes here
};

// Showing default values
const honeybadgerNextJsConfig = {
  // Disable source map upload (optional)
  disableSourceMapUpload: false,

  // Hide debug messages (optional)
  silent: true,

  // More information available at @honeybadger-io/webpack: https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/webpack
  webpackPluginOptions: {
    // Required if you want to upload source maps to Honeybadger
    apiKey: process.env.NEXT_PUBLIC_HONEYBADGER_API_KEY,

    // Required if you want to upload source maps to Honeybadger
    assetsUrl: process.env.NEXT_PUBLIC_HONEYBADGER_ASSETS_URL,

    revision: process.env.NEXT_PUBLIC_HONEYBADGER_REVISION,
    endpoint: "https://api.honeybadger.io/v1/source_maps",
    ignoreErrors: false,
    retries: 3,
    workerCount: 5,
    deploy: {
      environment:
        process.env.NEXT_PUBLIC_VERCEL_ENV ||
        process.env.VERCEL_ENV ||
        process.env.NODE_ENV,
      repository: "https://url.to.git.repository",
      localUsername: "username",
    },
  },
};

module.exports = setupHoneybadger(moduleExports, honeybadgerNextJsConfig);

Note: If you want to upload source maps to Honeybadger, ensure that disableSourceMapUpload is set to false and that apiKey and assetsUrl properties are set in webpackPluginOptions.

Note: The value of assetsUrl should be the URL to your domain suffixed with _next. For example if you app is deployed on Vercel and has the domain my-app.vercel.app, the value of assetsUrl should be https://my-app.vercel.app/_next.

Optionally, you can use Honeybadger’s Error Boundary component to collect additional React contextual information for errors that occur in your React components. Simply wrap the Component prop in your _app.js file:

import { Honeybadger, HoneybadgerErrorBoundary } from "@honeybadger-io/react";

function MyApp({ Component, pageProps }) {
  return (
    <HoneybadgerErrorBoundary honeybadger={Honeybadger}>
      <Component {...pageProps} />
    </HoneybadgerErrorBoundary>
  );
}

export default MyApp;

You can read more about Error Boundaries in the React documentation.

Note

Errors that happen in development and test environments are not reported by default. To always report errors or to change the defaults, see Environments and Versions.

Reporting errors

The above configuration will automatically report errors to Honeybadger in most cases (see Limitations), but you can also report errors manually:

import { Honeybadger } from "@honeybadger-io/react";

Honeybadger.notify(error);

Identifying users

Honeybadger can track which users have encountered each error. To identify the current user in error reports, add a user identifier and/or email address with Honeybadger.setContext:

import { Honeybadger } from "@honeybadger-io/react";

Honeybadger.setContext({
  user_id: 123,
  user_email: "user@example.com",
});

Sending additional context

Sometimes additional application state may be helpful for diagnosing errors. You can arbitrarily specify additional key/value pairs when you invoke setContext.

import { Honeybadger } from "@honeybadger-io/react";

Honeybadger.setContext({
  active_organization: 55,
  custom_configuration: false,
});

Clearing context

If your user logs out or if your context changes during the React component lifetime, you can set new values as appropriate by invoking setContext again.

Additionally, if needed, you can clear the context by invoking clear:

import { Honeybadger } from "@honeybadger-io/react";

// Set the context to {}
Honeybadger.clear();

Advanced usage

@honeybadger-io/nextjs is built on @honeybadger-io/js and @honeybadger-io/react.

See the Honeybadger JavaScript integration documentation for additional customization options, as well as the dedicated React integration guide.

Source map upload and tracking deploys

Honeybadger can automatically un-minify your code if you provide a source map along with your minified JavaScript files. See our Source Map Guide for details.

Fill in the values under webpackPluginOptions in your next.config.js file to upload source maps to Honeybadger.

You can notify Honeybadger when you’ve deployed a new build. Honeybadger will associate an error report with a specific revision number (matching the revision field in the configuration passed to Honeybadger.configure, found in one of your honeybadger.[server|client|edge].config.js files). Set deploy information in your Honeybadger’s Next.js configuration under the webpackPluginOptions.deploy key.

For more information, see @honeybadger-io/webpack documentation.

Collect User Feedback

When an error occurs, a form can be shown to gather feedback from your users. Honeybadger can automatically show the form by setting the showUserFeedbackFormOnError prop to true:

<HoneybadgerErrorBoundary
  honeybadger={honeybadger}
  showUserFeedbackFormOnError={true}
>
  <App />
</HoneybadgerErrorBoundary>

Read more about this feature here.

Limitations

The following limitations are known to exist and will be tackled in future releases:

• Issue link: A custom error component is used to report uncaught exceptions to Honeybadger. This is necessary because Next.js does not provide a way to hook into the error handler. This is not a catch-all errors solution. If you are using the Pages Router, there are some caveats to this approach, as reported here. This is a limitation of Next.js, not Honeybadger’s Next.js integration. Errors thrown in middlewares or API routes will not be reported to Honeybadger, since when they reach the error component, the response status code is 404 and no error information is available. Additionally, there is an open issue about 404 being reported with Next.js apps deployed on Vercel, when they should be reported as 500. If you are using the App Router, these limitations do not apply, because errors thrown in middlewares or API routes do not reach the custom error component but are caught by the global window.onerror handler. However, some other server errors (i.e. from data fetching methods) will be reported with minimal information, since Next.js will send a generic error message to this component for better security.
• Issue link: Source maps for the Edge runtime are not supported yet.

Sample applications

Two sample applications are available in the examples folder. Follow the README instructions to run them.