Migrate from Sentry to @nais/apm ¶

This guide takes a frontend app off Sentry (@sentry/browser, @sentry/react, @sentry/nextjs, …) and onto @nais/apm, the Nais browser telemetry SDK. Your errors stop going to sentry.gc.nav.no and start showing up as issues in Nais APM, on your team's own Grafana stack.

Who this is for ¶

You're on this page if your app calls Sentry.init and friends today. Many of these apps also already run Grafana Faro alongside Sentry — @nais/apm is a thin, opinionated wrapper over Faro with a Sentry-like developer experience, so if that's you, this migration also collapses two SDKs into one.

The end state is idiomatic @nais/apm with Sentry fully removed: no @sentry/* dependency, no DSN, no withSentryConfig, no SENTRY_AUTH_TOKEN.

Concept map ¶

Step-by-step recipe ¶

1. Remove Sentry ¶

Drop every @sentry/* package and its config from package.json:

npm uninstall @sentry/browser @sentry/react @sentry/nextjs @sentry/webpack-plugin

Delete the DSN and auth-token wiring while you're here — you won't need them:

2. Add @nais/apm ¶

@nais/apm is published to the GitHub Package Registry. Configure the registry (one-time, in .npmrc) and install — the full steps are in Track frontend errors:

npm install @nais/apm@0.4.0

The React helpers (error boundary, route tracking, Next.js client init) live in the @nais/apm/react entry point.

3. Swap Sentry.init → init() ¶

There is no DSN and, on Nais, nothing to configure — init() reads the app name, version, environment, team, and collector URL from the Nais meta tags / NAIS_* env.

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  release: import.meta.env.VITE_SENTRY_RELEASE,
  environment: globalThis.location.hostname,
  integrations: [Sentry.breadcrumbsIntegration({ console: false })],
  ignoreErrors: ['TypeError: Failed to fetch'],
  beforeSend: (event) => (isNoise(event) ? null : event),
});

import { init } from '@nais/apm';

init({
  // app / version / environment / namespace all resolve from Nais — omit them.
  ignoreErrors: [/Failed to fetch/],
  beforeSend: (item) => (isNoise(item) ? null : item),
});

import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  allowUrls: ['arbeidsplassen.nav.no'],
  ignoreErrors: ['TypeError: Failed to fetch'],
  beforeSend(event, hint) { return isNoise(hint) ? null : event; },
});

export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

import { initNaisAPMClient } from '@nais/apm/react';

initNaisAPMClient({
  namespace: 'my-team', // or resolved from a <meta name="nais-team"> tag / NAIS_TEAM
  ignoreErrors: [/Failed to fetch/],
  tracing: true, // optional — see step 5
});

4. Replace the error boundary and route tracking ¶

Error boundary — swap Sentry.ErrorBoundary for ApmErrorBoundary:

// Before
import * as Sentry from '@sentry/react';
<Sentry.ErrorBoundary fallback={<TekniskFeilSide />}>
  <App />
</Sentry.ErrorBoundary>

// After
import { ApmErrorBoundary } from '@nais/apm/react';
<ApmErrorBoundary fallback={<TekniskFeilSide />}>
  <App />
</ApmErrorBoundary>

ApmErrorBoundary reports through captureException exactly once, so caught render errors get the SDK's fingerprint/context pipeline. The withApmErrorBoundary(Component, props?) HOC mirrors Sentry.withErrorBoundary. The fallback can also be a render prop (error, resetError) => node.

Route tracking:

import {
  createRoutesFromChildren, matchRoutes, Routes, useLocation, useNavigationType,
} from 'react-router-dom';
import { enableApmReactRouterV6, ApmRoutes } from '@nais/apm/react';

enableApmReactRouterV6({
  createRoutesFromChildren, matchRoutes, Routes, useLocation, useNavigationType,
});

// <ApmRoutes> instead of <Routes>

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

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

5. Tracing (optional) ¶

If you used browserTracingIntegration / tracesSampleRate, enable tracing with one flag. @grafana/faro-web-tracing is lazily loaded so it stays out of your bundle unless you turn it on:

init({ tracing: true });

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

6. Delete sourcemap upload ¶

Remove the entire @sentry/webpack-plugin / withSentryConfig sourcemap-upload step and the SENTRY_AUTH_TOKEN it needed:

// next.config.ts — DELETE the withSentryConfig wrapper
const nextConfig = withSentryConfig(baseConfig, {
  org: 'nav',
  project: 'my-app',
  sentryUrl: 'https://sentry.gc.nav.no/',
  authToken: process.env.SENTRY_AUTH_TOKEN,
});
export default nextConfig; // -> export default baseConfig;

There is nothing to replace it with. The Nais telemetry collector resolves minified stack traces server-side by fetching your .map files from the CDN (cdn.nav.no) at read time. You only need to emit sourcemaps and deploy them alongside your bundle — no upload, no auth token. Follow Sourcemap deobfuscation for the build settings and the CDN requirement.

7. Replace Sentry Replay ¶

If you ran replayIntegration(), use sessionReplay:

init({ sessionReplay: { enabled: true, mode: 'on-error' } });

This defaults to the events tier — a DOM-free interaction timeline, safe by construction. It is not a like-for-like replacement for Sentry's full DOM recording; opting into DOM capture is a deliberate, personvernombud-gated decision. Read the session replay limitations and Enable session replay before you turn anything on.

8. Move alerting to Grafana ¶

Sentry alert rules don't come across. Recreate them as Grafana alerts from Nais APM templates (error rate, exception spike, new exceptions, web vitals) — delivered through your team's Grafana contact points.

Differences from Sentry ¶

@nais/apm is deliberately not a drop-in for the whole Sentry API. Before you delete @sentry/*, read the canonical Limitations & differences from Sentry — it covers the unsupported APIs (addBreadcrumb, scopes, manual spans, setExtra/setExtras, lastEventId, showReportDialog, withProfiler, React Router v5/v7), the source-map and replay model, and more.

The two gotchas that bite migrations hardest:

A few migration-specific pointers, each covered in full on its own page:

Migration checklist ¶

Related ¶