Source maps

See original file names and line numbers in your stack traces.

Install the bundler plugin

terminal

pnpm add -D @observerkit/vite

The plugin uploads source maps on each build and injects debug IDs for accurate stack trace mapping.

Configure

Add the plugin to your Vite config. Source maps are enabled automatically.

vite.config.ts

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import observerkit from "@observerkit/vite"

export default defineConfig({
  plugins: [
    react(),
    observerkit({
      projectKey: "ok_proj_...",
    }),
  ],
})

Options

projectKeystringRequired. Your project key.

endpointstringIngest API URL. Defaults to ingest.observerkit.com.

deleteAfterUploadbooleanRemove .map files from output after upload and strip sourceMappingURL references so nothing dangles. Defaults to true.

Verify the build uploaded

A production build prints one upload summary per output directory. A framework that builds several environments prints one per environment.

[ObserverKit] Enabling build.sourcemap for source map upload
[ObserverKit] Uploaded 12 source map(s) from /app/build/client
[ObserverKit] Deleted 12 .map files from output
[ObserverKit] Uploaded 3 source map(s) from /app/build/server
[ObserverKit] Deleted 3 .map files from output

If you see Output directory not found or No .map files found in, the plugin scanned somewhere your build does not write to. The message names the path it tried. Transient upload failures are retried twice and log each attempt, so a slow build is explicable rather than mysterious.

No .map file should remain in your output afterwards. With deleteAfterUpload left on, running find build -name "*.map" should print nothing.

You do not have to catch this in a build log. If your app sends errors referencing a build whose source maps never arrived, your project settings page says so, along with the date of your last successful upload. A project that has never uploaded and one that stopped uploading are called out differently, because they point at different causes.

Verify a stack trace resolves

Drop a button into your app that throws, trigger it after a production build, then check your dashboard. The stack trace should show original file names and line numbers.

<button
  onClick={() => {
    throw new Error("test error")
  }}
>
  Throw test error
</button>