Next.js Error & Exception Tracking
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
- 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
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
- Next.js custom error component
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: If you already have an _error.js
file in your pages
directory, a backup
will be created with the name _error.js.bak
.
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.
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:
-
Open Issue link: A custom
_error.js
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. 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 _error.js, 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. - Open Issue link: Source maps for the Edge runtime are not supported yet.
Sample application
A separate repository, nextjs-with-honeybadger exists with an example app using this package. Follow the README instructions to run the example app.
Package:
@honeybadger-io/nextjs
Version:
5.6.0
Repository:
https://github.com/honeybadger-io/honeybadger-js/tree/master/packages/nextjs