# Okapi install guide — Next.js

Okapi speaks the Sentry ingest wire format: this is the standard `@sentry/nextjs` SDK, pointed at your own Okapi instance instead of Sentry's.

The DSN in this generic guide is a placeholder. Get the real DSN from Project → Settings → DSN Keys. An agent with an admin Okapi MCP credential can also call `get_dsn`. Do not invent a DSN.

Do not run the Sentry wizard or any setup that signs in to Sentry's hosted service; nothing in this setup should contact it.

## 1. Install

```bash
npm install @sentry/nextjs
```

## 2. Initialize

### `sentry.server.config.ts`

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "http://YOUR_PUBLIC_KEY@YOUR_OKAPI_HOST/YOUR_PROJECT_ID",
  environment: "production",
});
```

### `sentry.edge.config.ts`

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "http://YOUR_PUBLIC_KEY@YOUR_OKAPI_HOST/YOUR_PROJECT_ID",
  environment: "production",
});
```

### `instrumentation-client.ts`

```typescript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "http://YOUR_PUBLIC_KEY@YOUR_OKAPI_HOST/YOUR_PROJECT_ID",
  environment: "production",
});

export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
```

### `instrumentation.ts`

```typescript
import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// Captures errors from Server Components, middleware and proxies
export const onRequestError = Sentry.captureRequestError;
```

### `next.config.ts`

```typescript
import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs/config";

process.env.SENTRY_CLI_NO_TELEMETRY ||= "1";

const nextConfig: NextConfig = {};

export default withSentryConfig(nextConfig, {
  sourcemaps: { deleteSourcemapsAfterUpload: true },
  sentryUrl: "https://<your-okapi-host>",
  org: "<your-okapi-host>",
  project: "<project-slug>",
  authToken: process.env.SENTRY_AUTH_TOKEN,
  telemetry: false,
});
```

For Next.js 15.3+ App Router, put instrumentation.ts next to app (or src/app), with the other runtime config files beside it; merge next.config.ts into your existing config. If productionBrowserSourceMaps is already set, keep it true and retain the explicit sourcemaps.deleteSourcemapsAfterUpload option; false prevents client map generation. On Next.js 15.0–15.2, this guide covers server capture only; client-side capture needs Next.js 15.3+. Next.js 14 is not covered by this guide (it needs `next.config.mjs` and `experimental.instrumentationHook`). Create an upload token in Settings → Source maps and set SENTRY_AUTH_TOKEN in the build environment. When migrating from Sentry, replace Sentry's SENTRY_AUTH_TOKEN with an Okapi upload token and delete any leftover .env.sentry-build-plugin file (the plugin loads it into process.env). The config defaults SENTRY_CLI_NO_TELEMETRY to 1. Set SENTRY_CLI_NO_TELEMETRY=1 in the build environment too. The plugin's telemetry: false option does not disable CLI telemetry. Set url or sentryUrl to this instance's OKAPI_BASE_URL. A fresh CLI refuses uploads to a different host, but cached regions per org are honoured. Use this instance's host as org to isolate its CLI region cache; dotted hosts cannot collide with sentry.io slugs. Without a token, the build succeeds and skips uploads. See https://useokapi.app/docs/sdk-setup#source-map-uploads. Place the test route under src/app if that is your app directory. Request GET /api/okapi-test after starting the app, then remove the test route. In a one-off Node script, await Sentry.flush(2000); a running request needs no flush.

## 3. Send a test event

### `app/api/okapi-test/route.ts`

```typescript
import * as Sentry from "@sentry/nextjs";

export const dynamic = "force-dynamic";

export function GET() {
  Sentry.captureException(new Error("Okapi test event"));
  return new Response("Okapi test event sent");
}
```

## 4. Verify

Open the instance's dashboard → Issues. The test event should appear within a few seconds as a new issue. If the instance's MCP server exposes a `verify_installation` tool, call that instead of checking by hand — it reports the SDK name/version and whether only a synthetic test event has arrived yet.

## More

- Structured logs (same DSN, no separate shipper) and source map uploads: https://useokapi.app/docs/sdk-setup
- Connect over MCP once the SDK is wired up: https://useokapi.app/docs/mcp-agents