Connect Next.js to Bugsink
Next.js runs your application in the browser and on the server. Bugsink can capture failures from both sides and use production source maps to show the application code behind a bundled stack trace.
This guide adds the Next.js SDK, configures its browser and server entry points, and uploads source maps during a production Webpack build. To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.
Install the Next.js SDK
Install version 10 of the open-source Sentry SDK for Next.js. Bugsink accepts the Sentry event protocol, so the SDK can send browser and server errors directly to your Bugsink project:
npm install @sentry/nextjs@10npm install @sentry/nextjs@10
The major-version constraint is temporary. SDK 11 can send events to Bugsink, but its build-time source-map uploader is not compatible yet; the exact boundary is covered under Limitations.
Initialize the browser SDK
Create instrumentation-client.js in the project root. Next.js loads this
module before your client application, so the SDK can register its normal
handlers for uncaught errors and unhandled promise rejections:
import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, }); export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, }); export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
The NEXT_PUBLIC_ prefix makes the project DSN available in the browser
bundle. A DSN identifies the destination project; it is not an administrative
or source-map upload token.
Initialize the server SDK
Create one small configuration module for the Node.js runtime and another for the Edge runtime. Both read the server-side DSN from the environment:
import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.SENTRY_DSN, }); :::javascript import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.SENTRY_DSN, });import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.SENTRY_DSN, }); :::javascript import * as Sentry from "@sentry/nextjs"; Sentry.init({ dsn: process.env.SENTRY_DSN, });
Next.js discovers server instrumentation through src/instrumentation.js.
Load the right configuration for each runtime and export onRequestError so
unhandled App Router and server-rendering failures are reported with their
request context:
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"); } } export const onRequestError = Sentry.captureRequestError;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"); } } export const onRequestError = Sentry.captureRequestError;
Report App Router rendering errors
An App Router global error component catches rendering failures which React
handles before they become ordinary uncaught browser errors. Capture its
error prop explicitly, then render your application’s normal fallback UI:
"use client"; import * as Sentry from "@sentry/nextjs"; import NextError from "next/error"; import { useEffect } from "react"; export default function GlobalError({ error }) { useEffect(() => { Sentry.captureException(error); }, [error]); return ( <html> <body> <NextError statusCode={0} /> </body> </html> ); }"use client"; import * as Sentry from "@sentry/nextjs"; import NextError from "next/error"; import { useEffect } from "react"; export default function GlobalError({ error }) { useEffect(() => { Sentry.captureException(error); }, [error]); return ( <html> <body> <NextError statusCode={0} /> </body> </html> ); }
If your application has route-level error.js files, capture their error
props in the same way because they take precedence over global-error.js.
Upload source maps during the production build
Wrap your existing Next.js configuration with withSentryConfig. The plugin
creates browser and server source maps, adds matching debug IDs to the built
files, and uploads the result to Bugsink:
import { withSentryConfig } from "@sentry/nextjs/config"; /** @type {import('next').NextConfig} */ const nextConfig = { cacheComponents: true, partialPrefetching: true, }; export default withSentryConfig(nextConfig, { org: "bugsink", project: process.env.SENTRY_PROJECT, sentryUrl: process.env.SENTRY_URL, telemetry: false, release: { create: false, finalize: false, }, sourcemaps: { deleteSourcemapsAfterUpload: false, }, });import { withSentryConfig } from "@sentry/nextjs/config"; /** @type {import('next').NextConfig} */ const nextConfig = { cacheComponents: true, partialPrefetching: true, }; export default withSentryConfig(nextConfig, { org: "bugsink", project: process.env.SENTRY_PROJECT, sentryUrl: process.env.SENTRY_URL, telemetry: false, release: { create: false, finalize: false, }, sourcemaps: { deleteSourcemapsAfterUpload: false, }, });
Keep your own nextConfig options. The org value is only a compatibility
placeholder because Bugsink projects do not belong to an organization. Release
creation and finalization are disabled because debug-ID source maps do not need
the release-management API. You may omit deleteSourcemapsAfterUpload: false
if you do not need to retain the generated maps after upload.
Create a project-bound Bugsink token with the debug-files:upload capability
and keep it in your build environment. Then supply the Bugsink URL, project
slug, upload token, and both DSN variables when you make the production build:
NEXT_PUBLIC_SENTRY_DSN=https://key@bugsink.example/1 \ SENTRY_DSN=https://key@bugsink.example/1 \ SENTRY_URL=https://bugsink.example \ SENTRY_PROJECT=your-project-slug \ SENTRY_AUTH_TOKEN=your-project-token \ npm run buildNEXT_PUBLIC_SENTRY_DSN=https://key@bugsink.example/1 \ SENTRY_DSN=https://key@bugsink.example/1 \ SENTRY_URL=https://bugsink.example \ SENTRY_PROJECT=your-project-slug \ SENTRY_AUTH_TOKEN=your-project-token \ npm run build
This guide uses next build --webpack. Upload the source maps for every build
before that build can receive production traffic.
Trigger a browser error
Start the production server with its server-side DSN:
PORT=3000 \ SENTRY_DSN=https://key@bugsink.example/1 \ npm startPORT=3000 \ SENTRY_DSN=https://key@bugsink.example/1 \ npm start
For this setup check, a client component calls ordinary inventory code which deliberately throws when an unavailable item is reserved:
export function reserveProduct(sku, quantity) { const available = 0; if (quantity > available) { throw new Error( `Cannot reserve ${quantity} unit of ${sku}: only ${available} remain [nextjs-browser]`, ); } }export function reserveProduct(sku, quantity) { const available = 0; if (quantity > available) { throw new Error( `Cannot reserve ${quantity} unit of ${sku}: only ${available} remain [nextjs-browser]`, ); } }
Open http://127.0.0.1:3000/ and click Reserve desk lamp. The browser still
handles the uncaught exception normally; the SDK reports it in the background.
See the original browser source in Bugsink
Open the new issue in Bugsink. The uploaded map translates the production browser chunk back to the inventory module and shows the exact line that threw.
Error
That’s it: browser failures from the production build now reach Bugsink with their original Next.js source.
Check an App Router route
The server integration also reports unhandled route-handler failures. This route deliberately raises an application exception for a missing product:
export async function GET(_request, { params }) { const { sku } = await params; throw new Error(`Product ${sku} was not found [nextjs-server]`); }export async function GET(_request, { params }) { const { sku } = await params; throw new Error(`Product ${sku} was not found [nextjs-server]`); }
Open http://127.0.0.1:3000/api/products/MISSING-404. Next.js returns its
normal 500 response, while Bugsink shows the failed request and maps the
production server chunk back to line 4 of the route handler.
Error
Server route failures now reach the same Bugsink project with the request and their original route source.
Limitations
The SDK 11 event transport works with Bugsink, but its automatic Webpack
source-map uploader currently rejects the relative chunk-upload URL returned
by Bugsink. Running sentry-cli sourcemaps inject afterwards is not a safe
fallback: it adds a second, different debug ID while the event still refers to
the ID injected by the plugin. Keep the @sentry/nextjs@10 constraint for
source-mapped builds until this exchange is fixed. The behavior is tracked in
Bugsink issues #109,
#133, and
#157.
This setup deliberately uses the Webpack production build. Turbopack source map upload is not covered by this guide.
For SDK-wide capture options and other JavaScript frameworks, return to the JavaScript guide.
