Next.js ve Node.js

@errorbird/nextjs, Next.js uygulamasının sunucu hatalarını, tarayıcı hatalarını ve React hata sınırlarının yakaladığı render hatalarını Errorbird'e gönderir; derlemeden sonra source map'leri yükler. Kurulum üç dosyadır.

Hatalar üç yerden toplanır:

Nerede	Neyle	Örnek
Sunucu	`instrumentation.ts` → `onRequestError`	Server Component, route handler, server action, proxy
Tarayıcı	`instrumentation-client.ts`	Olay işleyicideki hata, reddedilen promise
React hata sınırı	`error.tsx` / `global-error.tsx` → `useReportError`	İstemci bileşeninin render hatası

Next.js 15.3 ve üstü (App Router) gerekir. Sunucu ve tarayıcı hataları aynı projeye, aynı gruplama kurallarıyla düşer. Next.js kullanmayan Node.js uygulamaları için aşağıdaki bölüme bakın.

Kurulum

npm install @errorbird/nextjs

Ortam değişkenleri (.env ya da barındırma panelinizdeki ayarlar):

ERRORBIRD_SECRET_KEY=ebrd_secret_…          # yalnızca sunucu
NEXT_PUBLIC_ERRORBIRD_KEY=ebrd_pub_…        # tarayıcı; publishable anahtar
[email protected]     # ör. commit SHA; source map'ler bu adla eşleşir

Secret anahtarın adı NEXT_PUBLIC_ ile başlamamalıdır: Next.js o önekli her değeri tarayıcıya giden koda gömer. Publishable anahtarın izinli alan adları listesine sitenizin adresini ekleyin.

Sunucu: `instrumentation.ts`

Projenin kökünde (ya da src/ altında):

import { captureRequestError, register as registerErrorbird } from '@errorbird/nextjs/server'

export function register() {
  registerErrorbird()
}

export const onRequestError = captureRequestError

Bu kadarı bütün sunucu hatalarını gönderir; Node.js ve Edge ortamında aynı kod çalışır. Olaya rota (/siparis/[id]), rota türü (render, route, action), istek yöntemi ve yolu eklenir.

Tarayıcı: `instrumentation-client.ts`

import { init } from '@errorbird/nextjs/client'

init({
  key: process.env.NEXT_PUBLIC_ERRORBIRD_KEY!,
  release: process.env.NEXT_PUBLIC_ERRORBIRD_RELEASE,
})

Next.js bu dosyayı React'ten önce çalıştırır; sayfa geçişleri, tıklamalar ve ağ istekleri hatadan önceki adımlar olarak kaydedilir. Seçenekler tarayıcı SDK'sıyla aynıdır.

Hata sınırları: `error.tsx` ve `global-error.tsx`

React'in yakaladığı render hataları tarayıcının genel hata olayına ulaşmaz; hata sayfanızda gönderin:

'use client'
import { useReportError } from '@errorbird/nextjs/client'

export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  useReportError(error)
  return <button onClick={reset}>Tekrar dene</button>
}

Hata sunucuda oluştuysa (error.digest doludur) tarayıcıdan tekrar gönderilmez: sunucu onu onRequestError ile zaten gönderdi ve tarayıcıya gelen kopyanın mesajı gizlenmiştir. Kullanıcıya gösterdiğiniz digest kodu, olayın digest etiketinde durur; panelde onunla arayabilirsiniz.

Source map'ler

Tarayıcı hatalarının orijinal koda çevrilmesi için next.config.ts:

const nextConfig = {
  productionBrowserSourceMaps: true,
}

Derleme hattınızda, next build'den hemen sonra:

export NEXT_PUBLIC_ERRORBIRD_RELEASE="web@$(git rev-parse --short HEAD)"
npx next build
ERRORBIRD_SECRET_KEY="$ERRORBIRD_SECRET_KEY" npx errorbird-nextjs sourcemaps

Komut .next/static altındaki haritaları yükler ve siler: Next.js o klasörü olduğu gibi yayınlar, haritalar ise kaynak kodunuzu içerir. Silinmesin isterseniz --keep. Turbopack (Next.js 16) ve webpack çıktısının ikisi de desteklenir; Turbopack'in haritayı farklı adla üretmesi (40h_0x9t.js → 03ftdzq5.js.map) komut tarafından çözülür.

Sürüm aynı olmalı. Derlemedeki NEXT_PUBLIC_ERRORBIRD_RELEASE ile yüklemedeki sürüm birebir aynı değilse eşleme yapılmaz. İkisini de aynı ortam değişkeninden üretin.

Sunucu tarafındaki hataların stack'i derlenmiş dosyaları (.next/server/…) gösterir; Next.js sunucu kodunu varsayılan olarak küçültmediği için satırlar okunur kalır.

Ne gönderilir, ne gönderilmez

Gönderilmez: istek başlıkları (çerez, Authorization), istek gövdesi ve adresin sorgu dizesi (?token=…). Sorgu dizesini göndermek için registerErrorbird({ sendQueryString: true }).
redirect(), notFound() ve benzeri Next.js akış kontrolleri hata sayılmaz.
Geliştirme ortamı: sunucu tarafı varsayılan olarak yalnızca NODE_ENV=production iken gönderir; next dev'deki hatalar projenizi doldurmaz. Açmak için registerErrorbird({ enabled: true }).
Bir sunucu dakikada en fazla 60 olay gönderir (maxEventsPerMinute); döngüye giren bir hata kotanızı tüketmez.

Gönderimden önce olayı değiştirmek ya da atmak için beforeSend, belirli hataları yok saymak için ignoreErrors kullanılır.

Node.js (Express, NestJS…)

Next.js kullanmayan sunucular için @errorbird/node:

npm install @errorbird/node

import { init, captureException } from '@errorbird/node'

init({
  key: process.env.ERRORBIRD_SECRET_KEY!,
  release: process.env.ERRORBIRD_RELEASE,
  environment: 'production',
})

// Express: hata ara katmanı, rotalardan sonra
app.use((error, request, response, next) => {
  captureException(error, { url: request.path, method: request.method })
  next(error)
})

Yakalanmamış hatalar kendiliğinden gönderilir. Uygulamanın kendi uncaughtException dinleyicisi yoksa Node'un varsayılan davranışı korunur: hata yazdırılır, gönderim beklenir ve süreç 1 koduyla kapanır. SDK unhandledRejection dinlemez; dinlemek Node'un "reddedilen promise süreci kapatır" davranışını kapatırdı.

Sunucusuz ortamda (AWS Lambda, Vercel işlevleri) yanıt dönmeden önce await flush() çağırın; aksi hâlde işlev dondurulduğunda bekleyen gönderim kaybolabilir.

Derlenmiş (TypeScript, esbuild) bir sunucu için source map'ler:

ERRORBIRD_SECRET_KEY=… npx errorbird-sourcemaps --release [email protected] --delete dist