Sentry in Next.js: il minimo utile per non perdere errori

Risposta breve: esegui npx @sentry/wizard@latest -i nextjs, imposta SENTRY_DSN e inizializza l'SDK in instrumentation.ts; per gli errori di rendering aggiungi app/global-error.tsx. Da lì ogni eccezione arriva con stack trace e route.

Il wizard e cosa scrive

npx @sentry/wizard@latest -i nextjs
npx next build

Il wizard crea instrumentation.ts e instrumentation-client.ts, avvolge next.config.ts con withSentryConfig e scrive il DSN in .env.local. Leggi il diff prima di committare: la configurazione predefinita include l'upload delle source map.

Server: instrumentation.ts

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

export async function register() {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: process.env.NODE_ENV,
    tracesSampleRate: 0.1,
  });
}

export const onRequestError = Sentry.captureRequestError;

onRequestError è l'hook che Next.js chiama sugli errori di route: senza, gli errori lato server restano nei log e non diventano eventi. tracesSampleRate: 0.1 tiene il 10% delle transazioni, non degli errori.

Client: global-error.tsx

"use client";

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

export default function GlobalError({ error }: { error: Error }) {
  Sentry.captureException(error);
  return (
    
      
        Something went wrong.
      
    
  );
}

Questo file intercetta gli errori di rendering che sfuggono agli error boundary di segmento e sostituisce l'intera pagina. captureException va chiamato prima del return: un errore durante il render non dà una seconda occasione.

Cosa filtrare prima che sia troppo tardi

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  ignoreErrors: [/ResizeObserver loop/, /^NetworkError$/],
  beforeSend(event) {
    if (event.request?.headers) delete event.request.headers.cookie;
    return event;
  },
});

ResizeObserver e NetworkError sono rumore noto: riempiono la quota senza indicare un bug. Il filtro su headers.cookie evita di spedire sessioni al servizio, ed è un obbligo prima di mandare dati di utenti reali.

Limite dichiarato

Sentry è un servizio esterno: l'SDK è MIT, il servizio ospitato no. Ogni evento lascia la tua infrastruttura, quindi scegliere cosa inviare e per quanto conservarlo resta una tua responsabilità. L'alternativa self-hosted esiste ed è più onerosa da mantenere.

Dove continuare

Nel catalogo parti dalla libreria shadcn, dal record alert toast e dallo skeleton animato. Per il resto leggi gli error boundary in App Router, gli errori di build comuni e il confronto analytics Vercel o self-hosted.