React + Vite quickstart with @nais/apm ¶

Instrument a React single-page app (SPA) built with Vite using @nais/apm, the Nais browser telemetry SDK, and see your errors as issues in Nais APM. This is the fast path for a client-rendered React app: init at the entry point, a React error boundary, and route tracking for React Router.

Prerequisites ¶

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 — ApmErrorBoundary, enableApmReactRouterV6, ApmRoutes — live in the @nais/apm/react entry point.

1. Initialize at the entry point ¶

Call init() once, as early as possible, in your app's entry module — before you render. On Nais, everything resolves automatically except the team, which you pass as namespace:

// src/main.tsx
import { init } from '@nais/apm';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

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

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

init() is idempotent, so React Strict Mode's double render won't re-initialize. App name, version, environment, and the collector URL resolve 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.

2. Add an error boundary ¶

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

// src/App.tsx
import { ApmErrorBoundary } from '@nais/apm/react';

export default function App() {
  return (
    <ApmErrorBoundary fallback={<p>Noe gikk galt.</p>}>
      <Routes /> {/* your app */}
    </ApmErrorBoundary>
  );
}

The fallback can also be a render prop (error, resetError) => node, and withApmErrorBoundary(Component, props?) gives you the HOC form.

3. Track route changes (React Router) ¶

For client-side navigation, report route changes so pageviews and errors carry the right URL. @nais/apm re-exports faro-react's route tracking as ApmRoutes. Call enableApmReactRouterV6 once after init(), passing your own react-router-dom exports (the SDK never imports react-router itself, which keeps its version out of its dependency tree), then render <ApmRoutes> where you'd render <Routes>:

// src/main.tsx — after init()
import {
  createRoutesFromChildren,
  matchRoutes,
  Routes,
  useLocation,
  useNavigationType,
} from 'react-router-dom';
import { enableApmReactRouterV6 } from '@nais/apm/react';

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

// wherever you render your routes
import { Route } from 'react-router-dom';
import { ApmRoutes } from '@nais/apm/react';

<ApmRoutes>
  <Route path="/" element={<Home />} />
  <Route path="/orders/:id" element={<Order />} />
</ApmRoutes>

4. Enable tracing (optional) ¶

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

init({
  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.

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 Vite:

// vite.config.js
export default {
  build: {
    sourcemap: true, // emits .map files
  },
};

A Vite SPA served from the CDN is the ideal case — the .map files sit next to the bundle. See Sourcemap deobfuscation → 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.

Related ¶