Next.js

Overview

The SDK has no Next.js dependency — use instrumentation-client.ts in the browser and instrumentation.ts on the server. Runtime details: Browser and Node.js.

• Client — top-level init() in instrumentation-client.ts (runs before the app is interactive, no React).
• Server — register() in instrumentation.ts when NEXT_RUNTIME === 'nodejs'; absolute endpoint and serverUrl.

Breadcrumbs and session IDs are not shared between client and server — each runtime has its own queue and session.

Client

Add instrumentation-client.ts at the project root (or in src/). Call init at module scope — Next bundles and runs this file before your UI hydrates.

// instrumentation-client.ts
import { init } from '@retrace-kit/sdk';

init({
  apiKey: process.env.NEXT_PUBLIC_RETRACE_KIT_API_KEY ?? '',
  endpoint: '/api/error-events',
  release: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
  environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? process.env.NODE_ENV,
});

Server

Add instrumentation.ts at the project root (or in src/). Register the SDK on the Node runtime only.

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME !== 'nodejs') {
    return;
  }

  const { init } = await import('@retrace-kit/sdk');

  const host = process.env.VERCEL_URL;
  init({
    apiKey: process.env.RETRACE_KIT_API_KEY ?? '',
  });
}

Server secrets stay in env vars without the NEXT_PUBLIC_ prefix. See serverUrl on the Node.js page.

Error boundaries

Uncaught errors in Server Components may not reach the client SDK. Report UI segment failures explicitly:

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

import { useEffect } from 'react';
import { captureException } from '@retrace-kit/sdk';

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

  return <h2>Something went wrong</h2>;
}

Use global-error.tsx the same way for root layout errors.

Route breadcrumbs

Export onRouterTransitionStart from the same instrumentation-client.ts file — still outside React:

// instrumentation-client.ts (continued)
import { init, addBreadcrumb } from '@retrace-kit/sdk';

init({ /* ... */ });

function routeValue(url: string): string {
  try {
    const parsed = new URL(url, window.location.origin);
    return parsed.pathname + parsed.search;
  } catch {
    return url;
  }
}

addBreadcrumb({
  type: 'route',
  name: 'pathname',
  value: routeValue(window.location.href),
});

export function onRouterTransitionStart(url: string) {
  addBreadcrumb({
    type: 'route',
    name: 'pathname',
    value: routeValue(url),
  });
}

On Next.js versions without instrumentation-client, use usePathname in a client component instead — see Breadcrumbs → Router.