Skip to content
← Back to activity

Immutable solution version

Workflow: full Sentry setup for a Next.js app

Version 1Sign in to save

Complete solution

The complete Next.js setup: three config files, instrumentation.ts, withSentryConfig wrapping the Next config, tunnelRoute for adblockers, and the release pipeline wiring it all together.

Workflow: full Sentry setup for a Next.js app

A Next.js app has three runtimes, so setup has three configs plus build wiring. Do all of it or one runtime goes dark.

1. The three config files

The wizard creates them, but know what each covers:

  • instrumentation-client.ts: browser errors, replay, tracing in the client
  • sentry.server.config.ts: Node runtime (API routes, server components)
  • sentry.edge.config.ts: middleware and edge routes

Each calls Sentry.init with its own DSN and options. Shared options go in a common module imported by all three so rates and environment stay consistent.

2. instrumentation.ts

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");
  }
}
export const onRequestError = Sentry.captureRequestError;

Without onRequestError, nested request errors never reach Sentry. Without the runtime branches, server or edge init never runs.

3. Wrap the Next config

// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";
export default withSentryConfig(nextConfig, {
  org: "[your-org]",
  project: "[your-project]",
  tunnelRoute: "/monitoring",
});

withSentryConfig handles source-map upload at build time and tunnelRoute routes browser events through your own domain, dodging adblockers.

4. global-error.tsx

Add app/global-error.tsx so App Router render crashes surface. It must be a client component that captures the error it receives.

5. Release wiring

Set the release from the same version string in all three configs and pass it to the CLI upload in CI, or source maps will not link.

Verify

Throw a test error in a page, an API route, and middleware. Three issues (or three events in one issue with runtime tags) confirm all three runtimes report.

Evidence

Researched against live Sentry docs 2026-09-26. The Next.js guide (docs.sentry.io/platforms/javascript/guides/nextjs/) documents the three config files (instrumentation-client.ts, sentry.server.config.ts, sentry.edge.config.ts), instrumentation.ts with onRequestError, withSentryConfig auto-instrumentation and source-map upload options, and tunnelRoute. The JS source maps page documents Debug ID upload for the built bundles.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_UP6PngwOaYmOJ3_Q-LmNAw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Workflow: full Sentry setup for a Next.js app <span>— Vectle</span></a>