# Okapi install guide — SvelteKit

Okapi speaks the Sentry ingest wire format: this is the standard `@sentry/sveltekit` 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/sveltekit
```

## 2. Initialize

### `src/instrumentation.server.ts`

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

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

### `src/hooks.server.ts`

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

export const handleError = Sentry.handleErrorWithSentry();
export const handle = Sentry.sentryHandle();
```

### `src/hooks.client.ts`

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

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

export const handleError = Sentry.handleErrorWithSentry();
```

### `vite.config.ts`

```typescript
import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit/vite";
import { defineConfig } from "vite";

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

export default defineConfig({
  plugins: [
    sentrySvelteKit({
      autoUploadSourceMaps: true,
      sourcemaps: { filesToDeleteAfterUpload: ["./.*/**/*.map", "./build/**/*.map"] },
      sentryUrl: "https://<your-okapi-host>",
      org: "<your-okapi-host>",
      project: "<project-slug>",
      authToken: process.env.SENTRY_AUTH_TOKEN,
      telemetry: false,
    }),
    sveltekit(),
  ],
});
```

For SvelteKit 3, do not create svelte.config.js; pass existing configuration directly to sveltekit() in vite.config.ts, without the kit wrapper, and omit experimental.instrumentation because server instrumentation is enabled by default. Keep sentrySvelteKit before sveltekit() and merge config into existing files. If build.sourcemap is already set, use "hidden" and retain the explicit deletion globs. These are the SDK's own default globs, which it drops once build.sourcemap is set: ./.*/** covers hidden adapter output such as .svelte-kit, .vercel, .netlify and .svelte-kit/cloudflare (adapter-auto, the default, picks one of these), and ./build/** covers adapter-node and adapter-static. If your adapter writes elsewhere, add a glob for its output folder. Request GET /okapi-test after starting the app, then remove the test route. 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.

### Older SvelteKit versions

For SvelteKit 2.31 through 2.x, additionally merge this older-version configuration into svelte.config.js:

```javascript
const config = {
  kit: {
    experimental: {
      instrumentation: { server: true },
    },
  },
};
export default config;
```

Below SvelteKit 2.31, put the server init in hooks.server.ts instead.

## 3. Send a test event

### `src/routes/okapi-test/+server.ts`

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

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