Next.js quickstart with `@nais/apm` ¶

Instrument a Next.js frontend with @nais/apm, the Nais browser telemetry SDK, and see your errors as issues in Nais APM. Next.js is the most common frontend framework on Nais, so this is the fast path: client init, a React error boundary, route tracking, and — if you want it — distributed tracing.

This guide covers both routers:

App Router (app/) — the default since Next.js 13 and what most Next apps here use. Start here.
Pages Router (pages/) — the _app.tsx variant, including the Nais golden-path template. See the Pages Router section for the differences.

@nais/apm is pre-1.0. Pin an exact version and read the CHANGELOG before upgrading. This guide targets 0.4.0.

If your app calls Sentry.init today, follow Migrate from Sentry to @nais/apm instead — it maps every @sentry/nextjs call site to its @nais/apm equivalent and lists what's different.

Prerequisites ¶

A Next.js application (15 or newer for instrumentation-client.ts; the Pages Router pattern works on older versions too) deployed on Nais.
The @nais package registry configured in your .npmrc. This is a one-time setup — follow step 1 of Track frontend errors.

Install ¶

pnpm add @nais/apm@0.4.0
# or: npm install @nais/apm@0.4.0 / yarn add @nais/apm@0.4.0

The React helpers used below — initNaisAPMClient, ApmErrorBoundary, useApmRouteTracking — live in the @nais/apm/react entry point.

App Router ¶

1. Initialize the client ¶

On Next.js 15+, the client instrumentation hook instrumentation-client.ts runs once, early, in the browser — the ideal place to initialize telemetry. Create it at your project root (next to next.config.js):

// instrumentation-client.ts
import { initNaisAPMClient } from '@nais/apm/react';

initNaisAPMClient({
  namespace: 'my-team', // your Nais team — see the note below
});

initNaisAPMClient no-ops on the server (typeof window === 'undefined') and is idempotent, so it's safe under React Strict Mode's double-invoke and any repeated imports. Everything else — app name, version, environment, and the collector URL — resolves automatically from Nais meta tags or NAIS_* build env. On localhost, where no collector resolves, it sends nothing and echoes every signal to the console.

namespace is the Nais team that owns the app (its Kubernetes namespace). Nais APM attributes all telemetry by team, so it's effectively required. Pass it explicitly as shown, or let it resolve from a <meta name="nais-team" content="my-team"> tag or the NAIS_TEAM env — then you can drop the option entirely.

2. Add an error boundary ¶

Wrap your app in ApmErrorBoundary in the root layout. It reports each caught render error exactly once through captureException — so it picks up the SDK's fingerprint and context — and renders a fallback:

tsx

// app/layout.tsx
import { ApmErrorBoundary } from '@nais/apm/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="nb">
      <body>
        <ApmErrorBoundary fallback={<p>Noe gikk galt.</p>}>
          {children}
        </ApmErrorBoundary>
      </body>
    </html>
  );
}

ApmErrorBoundary is a client component, but it accepts your Server Component children as-is — no 'use client' needed in the layout. The fallback can also be a render prop (error, resetError) => node, and withApmErrorBoundary(Component, props?) gives you the HOC form.

Next.js also has its own route-segment error boundaries (error.tsx, global-error.tsx). These are separate from ApmErrorBoundary — to report errors they catch, call captureException from them:

tsx

// app/global-error.tsx
'use client';

import { captureException } from '@nais/apm';
import { useEffect } from 'react';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    captureException(error);
  }, [error]);

  return (
    <html lang="nb">
      <body>
        <h2>Noe gikk galt.</h2>
        <button onClick={reset}>Prøv igjen</button>
      </body>
    </html>
  );
}

3. Track route changes ¶

The App Router does client-side navigation without full page loads, so pathname changes need to be reported explicitly. There's no faro-react App Router integration; @nais/apm ships a small hook, useApmRouteTracking, that you feed Next's navigation values. Put it in a client component and mount it once in the layout:

tsx

// app/ApmRouteTracker.tsx
'use client';

import { usePathname, useSearchParams } from 'next/navigation';
import { useApmRouteTracking } from '@nais/apm/react';

export function ApmRouteTracker() {
  useApmRouteTracking(usePathname(), useSearchParams());
  return null;
}

tsx

// app/layout.tsx (add to the body)
import { Suspense } from 'react';
import { ApmRouteTracker } from './ApmRouteTracker';

// ...inside <body>, alongside {children}:
<Suspense fallback={null}>
  <ApmRouteTracker />
</Suspense>

useSearchParams() opts a component into client-side rendering. Wrapping the tracker in a <Suspense> boundary keeps that opt-in from bubbling up and forcing the rest of the page to render client-side during static generation.

4. Enable tracing (optional) ¶

To connect browser spans to your backend traces in Tempo, turn on tracing in the init call. @grafana/faro-web-tracing is lazily loaded, so it stays out of your bundle unless you enable it:

// instrumentation-client.ts
initNaisAPMClient({
  namespace: 'my-team',
  tracing: true,
});

Trace headers are propagated to your own origin and *.nav.no backends by default (a non-overridable security floor). Add more origins with tracing: { propagateExtraOrigins: ['https://api.partner.example'] }. Your backend still has to allow the traceparent CORS header and export spans to Tempo — see frontend-to-backend trace propagation.

Pages Router ¶

The Pages Router (pages/) — including navikt's golden-path Next.js template — works the same way, with two differences: where you initialize and how you track routes.

Initialize in `_app.tsx` ¶

There's no instrumentation-client.ts, so call initNaisAPMClient at module scope in your custom App. It no-ops on the server and is idempotent, so top-level is fine:

tsx

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { initNaisAPMClient, ApmErrorBoundary } from '@nais/apm/react';

initNaisAPMClient({ namespace: 'my-team' });

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ApmErrorBoundary fallback={<p>Noe gikk galt.</p>}>
      <Component {...pageProps} />
    </ApmErrorBoundary>
  );
}

Track routes with the router events ¶

The Pages Router exposes navigation through next/router events instead of usePathname(). Feed the new path into the same hook:

tsx

// pages/_app.tsx
import { useRouter } from 'next/router';
import { useApmRouteTracking } from '@nais/apm/react';

function App({ Component, pageProps }: AppProps) {
  const router = useRouter();
  useApmRouteTracking(router.asPath);
  // ...render as above
}

Tracing (tracing: true) and the error boundary work identically to the App Router.

Ship readable stack traces ¶

Stack traces resolve server-side from sourcemaps on the CDN — nothing to upload (how it works). You just have to emit them. For Next.js:

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};

Resolution only works for bundles served from the CDN. A purely server-rendered Next app that serves its own JS from the pod won't get resolved stack traces unless it also ships static assets to the CDN. See Sourcemaps → Requirements.

Don't send personal data ¶

Telemetry lands in a shared Loki instance every team can read, so identities must never reach it. setUser takes an opaque/hashed id only — emails, idents, and fødselsnummer are dropped in code — and a mandatory PII scrubber runs over every outgoing signal. See Privacy: PII scrubbing for the full rules.

See your errors as issues ¶

Deploy, then trigger an error. Open your service in Nais APM and go to the Issues tab. Your exception shows up as an issue, grouped with other occurrences, with its (deobfuscated) stack trace and impact. Filter the source to Browser to isolate frontend issues.

From there you can triage it or create an alert.

Track frontend errors with @nais/apm — the framework-agnostic tutorial and registry setup.
React + Vite quickstart — for React SPAs.
Migrate from Sentry to @nais/apm — call-site-by-call-site.
@nais/apm API reference — every export and option.
Sourcemap deobfuscation · Trace propagation

Next.js quickstart with `@nais/apm` ¶

Status: pre-release

Migrating off Sentry?

Prerequisites ¶

Install ¶

App Router ¶

1. Initialize the client ¶

`namespace` is your team

2. Add an error boundary ¶

3. Track route changes ¶

Wrap the tracker in `<Suspense>`

4. Enable tracing (optional) ¶

Pages Router ¶

Initialize in `_app.tsx` ¶

Track routes with the router events ¶

Ship readable stack traces ¶

Server-rendered assets don't get deobfuscated

Don't send personal data ¶

See your errors as issues ¶

Next.js quickstart with @nais/apm ¶

Status: pre-release

Migrating off Sentry?

Prerequisites ¶

Install ¶

App Router ¶

1. Initialize the client ¶

`namespace` is your team

2. Add an error boundary ¶

3. Track route changes ¶

Wrap the tracker in `<Suspense>`

4. Enable tracing (optional) ¶

Pages Router ¶

Initialize in _app.tsx ¶

Track routes with the router events ¶

Ship readable stack traces ¶

Server-rendered assets don't get deobfuscated

Don't send personal data ¶

See your errors as issues ¶

Related ¶

Next.js quickstart with `@nais/apm` ¶

Initialize in `_app.tsx` ¶