Next.js Quick Start
Learn how to set up highlight.io with your Next (frontend) application.
Install the npm package & SDK.
Install the npm package @highlight-run/next in your terminal.
# with npm
npm install @highlight-run/next
Initialize the client SDK.
Grab your project ID from app.highlight.io/setup, and set it as the projectID in the <HighlightInit/> component.
If you're using the original Next.js Page router, drop <HighlightInit /> in your _app.tsx file. For the App Router, add it to your top-level layout.tsx file.
// src/app/layout.tsx
import { HighlightInit } from '@highlight-run/next/client'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<>
<HighlightInit
projectId={'<YOUR_PROJECT_ID>'}
serviceName="my-nextjs-frontend"
tracingOrigins
networkRecording={{
enabled: true,
recordHeadersAndBody: true,
urlBlocklist: [],
}}
/>
<html lang="en">
<body>{children}</body>
</html>
</>
)
}
Identify users.
Identify users after the authentication flow of your web app. We recommend doing this in a useEffect call or in any asynchronous, client-side context.
The first argument of identify will be searchable via the property identifier, and the second property is searchable by the key of each item in the object.
For more details, read about session search or how to identify users.
import { H } from '@highlight-run/next/client';
function RenderFunction() {
useEffect(() => {
// login logic...
H.identify('jay@highlight.io', {
id: 'very-secure-id',
phone: '867-5309',
bestFriend: 'jenny'
});
}, [])
return null; // Or your app's rendering code.
}
Verify installation
Check your dashboard for a new session. Make sure to remove the Status is Completed filter to see ongoing sessions. Don't see anything? Send us a message in our community and we can help debug.
Wrap your Page Router endpoints
The Highlight Next.js SDK supports tracing for both Page and App Routers running in the Node.js runtime.
import { NextApiRequest, NextApiResponse } from 'next'
import { withPageRouterHighlight } from '@/app/_utils/page-router-highlight.config'
import { H } from '@highlight-run/next/server'
export default withPageRouterHighlight(async function handler(
req: NextApiRequest,
res: NextApiResponse,
) {
return new Promise<void>(async (resolve) => {
const { span } = H.startWithHeaders('page-router-span', {})
console.info('Here: /pages/api/page-router-trace.ts ⌚⌚⌚')
res.send(`Trace sent! Check out this random number: 0.9354150545368769`)
span.end()
resolve()
})
})
Wrap your App Router endpoints
The Highlight Next.js SDK supports tracing for both Page and App Routers running in the Node.js runtime.
import { NextRequest, NextResponse } from 'next/server'
import { withAppRouterHighlight } from '@/app/_utils/app-router-highlight.config'
import { H } from '@highlight-run/next/server'
export const GET = withAppRouterHighlight(async function GET(
request: NextRequest,
) {
return new Promise(async (resolve) => {
const { span } = H.startWithHeaders('app-router-span', {})
console.info('Here: /pages/api/app-router-trace/route.ts ⏰⏰⏰')
span.end()
resolve(new Response('Success: /api/app-router-trace'))
})
})
Verify your backend traces are being recorded.
Visit the highlight traces portal and check that backend traces are coming in.
More Next.js features?
See our fullstack Next.js guide for more information on how to use Highlight with Next.js.