Uso de Sentry para tracking de errores en React y Next.js: guía práctica

Apoya mi contenido:

Sentry te permite capturar errores, medir rendimiento y grabar replays en aplicaciones React y Next.js. En esta guía verás una implementación paso a paso para ambos casos: React SPA y Next.js (App Router o Pages Router), con ejemplos listos para copiar y pegar.

1) Conceptos rápidos

DSN: identificador de tu proyecto Sentry (en variables de entorno).
Release: versión del código que subes (SHA/semver) para mapear sourcemaps.
Environment: development, staging, production, etc.
Tracing/Performance: mide latencia de rutas, requests y renders.
Replay: sesión de usuario para ver qué ocurrió antes de un error.

2) React (Vite/CRA) — instalación mínima

# instala SDK para React
npm i @sentry/react

# (opcional) Replay y Performance vienen incluidos vía integraciones

2.1) Inicialización

Crea o edita tu punto de entrada (src/main.tsx o src/index.tsx):

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE, // 'development' | 'production' | ...
  release: import.meta.env.VITE_RELEASE, // e.g. CI SHA
  tracesSampleRate: 0.2,          // 20% de transacciones (ajusta según volumen)
  profilesSampleRate: 0.1,        // Perfilado de rendimiento (opcional)
  replaysSessionSampleRate: 0.1,  // 10% sesiones para Replay
  replaysOnErrorSampleRate: 1.0,  // 100% si hubo error
  integrations: [
    Sentry.replayIntegration(),
    Sentry.browserTracingIntegration(), // Performance
  ],
  beforeSend(event) {
    // ejemplo: eliminar datos sensibles
    if (event.request) delete event.request.cookies;
    return event;
  },
});

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(
  <Sentry.ErrorBoundary fallback={<p>Algo salió mal. Reintenta.</p>}>
    <App />
  </Sentry.ErrorBoundary>
);

2.2) Buenas prácticas en React

// Capturar manualmente
try {
  // algo que puede fallar
} catch (err) {
  Sentry.captureException(err, { tags: { area: 'checkout' } });
}

// Contexto del usuario (no PII si no lo necesitas)
Sentry.setUser({ id: '12345' }); // o removeUser()
Sentry.setContext('cart', { items: 3, total: 49.9 });

// Breadcrumbs (rastro de eventos)
Sentry.addBreadcrumb({ category: 'ui', message: 'Click en Comprar', level: 'info' });

3) Next.js — instalación

# SDK unificado para Next.js (soporta App y Pages Router)
npm i @sentry/nextjs

3.1) App Router (Next 13+)

Crea archivos de configuración (Sentry detecta automáticamente estos nombres):

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

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NEXT_PUBLIC_ENV || process.env.NODE_ENV,
  release: process.env.NEXT_PUBLIC_RELEASE,
  tracesSampleRate: 0.2,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.replayIntegration(),
    Sentry.browserTracingIntegration(),
  ],
});

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NEXT_PUBLIC_ENV || process.env.NODE_ENV,
  release: process.env.SENTRY_RELEASE,
  tracesSampleRate: 0.2,
  // En server puedes añadir más normalización si envías objetos grandes:
  normalizeDepth: 6,
});

Envuelve tu UI con el ErrorBoundary (opcional si usas error.tsx):

// app/layout.tsx
import * as Sentry from '@sentry/nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang=""es"">
      <body>
        <Sentry.ErrorBoundary fallback={<p>Se produjo un error.</p>}>
          {children}
        </Sentry.ErrorBoundary>
      </body>
    </html>
  );
}

Maneja errores en rutas y API:

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

export async function POST(req: Request) {
  try {
    const body = await req.json();
    // ... lógica
    return NextResponse.json({ ok: true });
  } catch (err) {
    Sentry.captureException(err, { tags: { endpoint: 'orders' } });
    return NextResponse.json({ error: 'Internal error' }, { status: 500 });
  }
}

3.2) Pages Router (Next <=12/13)

Inicializa en sentry.client.config.(js|ts) y sentry.server.config.(js|ts) igual que arriba. Para subir sourcemaps y mejorar DX puedes envolver el config:

// next.config.mjs
import { withSentryConfig } from '@sentry/nextjs';

const nextConfig = {
  reactStrictMode: true,
  // ...tu configuración
};

export default withSentryConfig(nextConfig, {
  // Opcional: subida automática de sourcemaps en build
  silent: true,
});

4) Variables de entorno recomendadas

# .env.production
SENTRY_DSN=...
NEXT_PUBLIC_SENTRY_DSN=...
SENTRY_AUTH_TOKEN=...            # para subir sourcemaps desde CI
SENTRY_ORG=tu-org
SENTRY_PROJECT=tu-proyecto
SENTRY_RELEASE=$GIT_COMMIT_SHA   # o semver, p.ej. 1.4.0
NEXT_PUBLIC_ENV=production

5) Sourcemaps (releases) desde CI/CD

Vincula errores al código fuente para obtener líneas reales:

# Ejemplo genérico con sentry-cli (GitHub Actions / CI)
npm i -D @sentry/cli

npx sentry-cli releases new $SENTRY_RELEASE
npx sentry-cli releases files $SENTRY_RELEASE upload-sourcemaps .next --url-prefix ""~/_next"" --rewrite
npx sentry-cli releases finalize $SENTRY_RELEASE

6) Muestras y privacidad

Sampling: ajusta tracesSampleRate / replaysSessionSampleRate según tráfico para controlar costos.
PII: evita enviar datos sensibles; usa beforeSend para limpiar eventos.
Entornos: deshabilita o reduce al mínimo el muestreo en development.

7) Pruebas rápidas

// Forzar un error en el cliente
button.addEventListener('click', () => {
  throw new Error('Prueba Sentry: botón roto');
});

// Forzar captura manual
Sentry.captureMessage('Evento informativo', 'info');

8) Panel de usuario y feedback

Puedes habilitar el User Feedback para que los usuarios envíen contexto cuando ocurre un error:

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  // ...
  integrations: [Sentry.feedbackIntegration({ colorScheme: 'system' })], // si tu versión lo soporta
});

9) Checklist de producción

DSN y environment correctos en cada despliegue.
release configurado y sourcemaps subidos.
Sample rates ajustados (tracing y replay) a tu volumen real.
ErrorBoundary activo o páginas error.tsx en Next.js.
Política de datos sensible en beforeSend.

Conclusión

Con una inicialización mínima y buenas prácticas (release + sourcemaps, muestreo y sanitización de datos), Sentry se convierte en una herramienta clave para detectar, entender y arreglar errores en React y Next.js sin fricción.

#Sentry #React #NextJS #Observabilidad #ErrorTracking #Performance #Replay #Frontend #JavaScript #DevOps