Skip to content
Learni
View all tutorials
Observabilité et Monitoring

How to Configure Advanced Sentry with Next.js in 2026

18 minEXPERT
MonitoringNext.jsSentry
Lire en français

Introduction

Sentry has become the go-to tool for error monitoring and application performance. In 2026, its integration with Next.js requires expert configuration including distributed tracing, encrypted source maps, and custom hooks. This tutorial walks you through a professional and maintainable setup step by step.

Prerequisites

  • Node.js 20+ and Next.js 15+
  • Sentry account with DSN and organization
  • Strong knowledge of TypeScript and edge runtime
  • Access to the CI/CD pipeline for source map uploads

Sentry SDK Installation

terminal
npx @sentry/wizard@latest -i nextjs

This command automatically installs @sentry/nextjs and generates the basic configuration files tailored for Next.js 15.

Advanced Client Configuration

sentry.client.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.2,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
  beforeSend(event) {
    if (event.exception?.values?.[0]?.type === 'ChunkLoadError') return null;
    return event;
  },
});

This file enables tracing, masked replays, and filters non-critical errors before sending them to Sentry.

Server and Edge Configuration

sentry.server.config.ts
import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.2,
  enableTracing: true,
  environment: process.env.VERCEL_ENV || 'development',
});

Dedicated configuration for the Node.js server and edge middlewares with consistent trace sampling.

Update next.config.js

next.config.js
const { withSentryConfig } = require('@sentry/nextjs');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your Next.js config
};

module.exports = withSentryConfig(nextConfig, {
  org: 'votre-org',
  project: 'votre-projet',
  silent: true,
  widenClientFileUpload: true,
  sourcemaps: { disable: false },
});

withSentryConfig automatically injects the webpack plugins required for uploading source maps in production.

Custom Error Capture

app/api/route.ts
import * as Sentry from '@sentry/nextjs';
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    throw new Error('Erreur métier simulée');
  } catch (error) {
    Sentry.captureException(error, {
      tags: { feature: 'api-users' },
      extra: { userId: '123' },
    });
    return NextResponse.json({ error: 'Erreur interne' }, { status: 500 });
  }
}

Manual capture with tags and business context for faster debugging in the Sentry dashboard.

Best Practices

  • Always mask sensitive data before sending
  • Use consistent tags to quickly filter errors
  • Configure alerts by environment (production vs staging)
  • Keep source maps private and encrypted
  • Monitor trace volume to control costs

Common Mistakes to Avoid

  • Forgetting to upload source maps in CI/CD
  • Leaving tracesSampleRate at 1.0 in production
  • Not filtering ChunkLoadError errors
  • Exposing the server DSN on the client side

Going Further

Deepen these techniques with our training on modern observability: https://learni-group.com/formations