Sentry in Next.js

Shahadat Robin

Software Developer, LemonHive

5 days ago

When developing any modern web application - monitoring and error tracking are essential to ensure a smooth user experience. One of the best tools for this purpose is Sentry.io - Which allows developers to track and resolve errors in real time. If you integrate Sentry into your app can save you a lot of time and effort in debugging and fixing issues.

In this article, we’ll walk through automatic configure Sentry into a Next.js project.

Why Sentry ?

To capture automatically uncaught client-side and server-side exceptions
To monitor errors across into client or server components, API routes, middleware, and edge functions
To understand error context through user actions, navigation, and network breakdowns
To intelligently group similar errors and reduce noise
To track errors by release and quickly identify regressions after deployment
To gain visibility into real-world performance issues in production
To debug UI issues (hard-to-reproduce) using session replay

Hold on! Before jump into the installation process, make sure that you have created sentry account.

Installation

Sentry provides an official setup wizard that automatically configures everything needed for a Next.js project. This is the recommended way to integrate Sentry, as it reduces manual errors and ensures best-practice defaults.

Run the following command from your project root:

npx @sentry/wizard@latest -i nextjs

After running the command, the wizard will:

Authenticate you with Sentry (via browser login)
Ask you to select an existing Sentry project or create a new one
Prompt you to enable optional features such as:
- Performance monitoring
- Session replay

Choose the features that best match your project requirements.

Once the wizard finishes, several files will be added or updated in your codebase. These changes enable error tracking across client components, server components, API routes, middleware, and edge functions.

=> Updated `next.config.ts`

import { withSentryConfig } from "@sentry/nextjs";

const nextConfig = {
  // your existing config
};

export default withSentryConfig(nextConfig);

Your next.config.ts file is now wrapped with withSentryConfig

Impacts:

Automatic source map uploads during build
Request tunneling to avoid ad blockers
Better stack traces in production
Build-time instrumentation

=> Client Instrumentation

// instrumentation-client.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Created this file for initializes Sentry on the browser/client side.

Impacts:

Capturing client-side runtime errors
Tracking navigation and user interactions
Collecting browser performance metrics

=> Server Instrumentation

// instrumentation.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Created this file for initializes Sentry for server-side execution, including:

Server Components
Route Handlers
API Routes

It ensures that server-side exceptions are captured before a response is sent to the client.

=> Edge & Server Config Files

Created:

sentry.server.config.ts for Node.js runtime
sentry.edge.config.ts for Edge runtime (middleware, edge functions)

This separation is important because edge environments have stricter runtime constraints.

=> Environment File (.env.sentry-build-plugin)

This file is used internally by Sentry’s build plugin to upload source maps securely during CI/CD or local builds.

=> Global Error Handler

Created or updated global error handler in your application to capture unhandled exceptions. For example, in a client-side component:

// global-error.ts

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 lang="en">
     <body>
       <NextError statusCode={0} />
     </body>
   </html>
 );
}

Finally

Once Sentry is running in your Next.js application, you’ll start to see real-time dashboards that surface the health and performance of your releases. Below is an example of what the Sentry project overview page looks like, together with an error list.

Happy monitoring...

Sentry in Next.js

Shahadat Robin

Software Developer, LemonHive

5 days ago

In this article, we’ll walk through automatic configure Sentry into a Next.js project.

Why Sentry ?

To capture automatically uncaught client-side and server-side exceptions
To monitor errors across into client or server components, API routes, middleware, and edge functions
To understand error context through user actions, navigation, and network breakdowns
To intelligently group similar errors and reduce noise
To track errors by release and quickly identify regressions after deployment
To gain visibility into real-world performance issues in production
To debug UI issues (hard-to-reproduce) using session replay

Hold on! Before jump into the installation process, make sure that you have created sentry account.

Installation

Run the following command from your project root:

npx @sentry/wizard@latest -i nextjs

After running the command, the wizard will:

Authenticate you with Sentry (via browser login)
Ask you to select an existing Sentry project or create a new one
Prompt you to enable optional features such as:
- Performance monitoring
- Session replay

Choose the features that best match your project requirements.

=> Updated `next.config.ts`

import { withSentryConfig } from "@sentry/nextjs";

const nextConfig = {
  // your existing config
};

export default withSentryConfig(nextConfig);

Your next.config.ts file is now wrapped with withSentryConfig

Impacts:

Automatic source map uploads during build
Request tunneling to avoid ad blockers
Better stack traces in production
Build-time instrumentation

=> Client Instrumentation

// instrumentation-client.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Created this file for initializes Sentry on the browser/client side.

Impacts:

Capturing client-side runtime errors
Tracking navigation and user interactions
Collecting browser performance metrics

=> Server Instrumentation

// instrumentation.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,
});

Created this file for initializes Sentry for server-side execution, including:

Server Components
Route Handlers
API Routes

It ensures that server-side exceptions are captured before a response is sent to the client.

=> Edge & Server Config Files

Created:

sentry.server.config.ts for Node.js runtime
sentry.edge.config.ts for Edge runtime (middleware, edge functions)

This separation is important because edge environments have stricter runtime constraints.

=> Environment File (.env.sentry-build-plugin)

This file is used internally by Sentry’s build plugin to upload source maps securely during CI/CD or local builds.

=> Global Error Handler

Created or updated global error handler in your application to capture unhandled exceptions. For example, in a client-side component:

// global-error.ts

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 lang="en">
     <body>
       <NextError statusCode={0} />
     </body>
   </html>
 );
}

Finally

Happy monitoring...

Sentry in Next.js

Why Sentry ?

Installation

=> Updated `next.config.ts`

=> Client Instrumentation

=> Server Instrumentation

=> Edge & Server Config Files

=> Environment File (.env.sentry-build-plugin)

=> Global Error Handler

Finally

Sentry in Next.js

Why Sentry ?

Installation

=> Updated `next.config.ts`

=> Client Instrumentation

=> Server Instrumentation

=> Edge & Server Config Files

=> Environment File (.env.sentry-build-plugin)

=> Global Error Handler

Finally

Related

Learn how to embed Sanity (v3) Studio inside Next.js project

How I Setup Next.js Repository for High-Velocity Projects

Sentry in Next.js

Why Sentry ?

Installation

=> Updated next.config.ts

=> Client Instrumentation

=> Server Instrumentation

=> Edge & Server Config Files

=> Environment File (.env.sentry-build-plugin)

=> Global Error Handler

Finally

Sentry in Next.js

Why Sentry ?

Installation

=> Updated next.config.ts

=> Client Instrumentation

=> Server Instrumentation

=> Edge & Server Config Files

=> Environment File (.env.sentry-build-plugin)

=> Global Error Handler

Finally

Related

Learn how to embed Sanity (v3) Studio inside Next.js project

How I Setup Next.js Repository for High-Velocity Projects

=> Updated `next.config.ts`

=> Updated `next.config.ts`