@observerkit/next

Next.js plugin for ObserverKit — injects debug IDs into your build output and uploads source maps after next build. Works with both Turbopack (Next.js 16+ default) and webpack mode.

Requirements

• Next.js >=15.4.1 (uses compiler.runAfterProductionCompile)
• Turbopack debug-IDs require Next.js >=16.0.0

Install

pnpm add -D @observerkit/next

Setup

Wrap your next.config.ts (or next.config.js) with withObserverkit:

// next.config.ts
import withObserverkit from "@observerkit/next"
import type { NextConfig } from "next"

const nextConfig: NextConfig = {
  // your existing Next.js config
}

export default withObserverkit(nextConfig, {
  projectKey: process.env["OBSERVERKIT_PROJECT_KEY"] ?? "",
})

What it does

• Enables productionBrowserSourceMaps: true
• Enables experimental.serverSourceMaps: true so webpack-mode server bundles emit maps too (Turbopack emits them natively)
• Enables turbopack.debugIds: true (Next.js 16+) so Turbopack emits standards-compliant debug IDs
• In webpack mode, injects equivalent debug-ID registration into JS chunks
• After next build, scans .next/ recursively for .map files and uploads the ones carrying a debugId to ObserverKit via compiler.runAfterProductionCompile
• By default, deletes all .map files from the build output afterwards — even when the upload fails or is skipped — and blanks sourceMappingURL= references in emitted chunks (webpack and Turbopack output), so source maps never ship and devtools never 404

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | projectKey | string | required | ObserverKit project key | | endpoint | string | https://ingest.observerkit.com | Ingest API base URL | | deleteAfterUpload | boolean | true | Delete every .map file from .next/ after the upload attempt (even on failure, so maps never ship) and blank sourceMappingURL references in chunks |

Notes

• The hook never throws. Upload failures are logged to console.error so they don't break the build.
• If you self-host your Next.js production server and rely on Node's --enable-source-maps for runtime stack traces, set deleteAfterUpload: false so server-side .map files stay on disk.
• When the user has already set productionBrowserSourceMaps or turbopack.debugIds, the plugin respects the user value.
• Both client (.next/static/) and server (.next/server/) sourcemaps are uploaded.
• When projectKey is empty (e.g. OBSERVERKIT_PROJECT_KEY unset in dev or CI), the plugin logs a warning and leaves your config untouched. It never breaks next dev or a keyless build.