The Highlight Next.js SDK adds additional features to Highlight, including:

• server-side error monitoring and linking to Highlight sessions: Highlight()

• automatic configuration of source map uploads: withHighlightConfig()

• automatic proxying for Highlight requests using Next.js rewrites: withHighlightConfig()

Getting Started

The features in this SDK require the Highlight client SDK to be installed, so please follow the Next.js instructions if you have not yet done so.

For server-side linking to Highlight sessions, your call to H.init should include the tracingOrigins setting. If you're going to use withHighlightConfig and proxy your Highlight requests with a rewrite, you should set backendUrl. See H.init() for more details.

H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    backendUrl: '/highlight-events',
    ...
});

SDK Setup

Import the @highlight-run/next Package

# with npm
npm install @highlight-run/next

# with yarn
yarn add @highlight-run/next

Wrapping your next.config.js

In order for Highlight to be aware of your project during build time, you need the HIGHLIGHT_SOURCEMAP_UPLOAD_API_KEY variable in your build environment. Refer to our environment variables doc to get this set up in your cloud provider of choice.

If you want to configure source map uploads during your production builds and enable the Next.js Highlight proxy rewrite, you can wrap your Next.js config with withHighlightConfig. See withHighlightConfig() for more details.

import { withHighlightConfig } from '@highlight-run/next'
export default withHighlightConfig({
	// your next.config.js options here
})

Next.js Custom Metrics

If you want to monitor backend errors, this API wrapper will send your errors to Highlight and link them to the session where the network request was made. Define a withHighlight wrapper with any common options in a common function file. For example, you can create a highlight.config.ts file in the root of your next.js codebase. See Highlight() for more details.

import { Highlight } from '@highlight-run/next'

export const withHighlight = Highlight()

You can then wrap each of your handlers in the Next.js api/ directory with the withHighlight function from the previous step.

import { withHighlight } from '../highlight.config'

const handler = async (req, res) => {
	res.status(200).json({ name: 'Jay' })
}

export default withHighlight(handler)

Wrapping your API routes

Refer to the next.js metrics docs in order to report custom metrics from your Next.js application.