Next.js ve React

Kurulum npm install @blipit/nextjs

@blipit/nextjs; tarayıcı hatalarını, web vitals'ı, oturum kaydını ve Hata bildir düğmesini layout'unuzdaki tek bir bileşenden, server component, route handler ve server action hatalarını ise instrumentation.ts içindeki tek bir satırdan sağlar. Düz React uygulamaları @blipit/browser kullanır.

Claude Code, Cursor veya başka bir yapay zekâ kodlama asistanına yapıştırın. Adımları ve kodu içerir. app.blipit.io'da API anahtarları altında aynı istem, anahtarınız yazılmış olarak gelir.
Video: Blipit'i her stack'e kurun, 0:32 itibarıyla

1Kurulum

sh
npm install @blipit/nextjs

2Anahtarlarınızı alın

app.blipit.io'da oturum açın ve kenar çubuğunda API anahtarları'nı, ardından projenizi açın. Her projenin iki anahtarı vardır. Public key blipit_pk_ ile başlar: tarayıcı ve uygulama koduna gider, yalnızca olay gönderebilir ve herkesin görmesi güvenlidir. Secret key blipit_sk_ ile başlar: sunucunuzda ya da Odoo'da kalır, asla tarayıcıda olmaz, çünkü sorunları okuyup değiştirebilir de. Secret key yalnızca bir kez, oluşturulduktan hemen sonra gösterilir, bu yüzden o anda kopyalayın; kaybederseniz Yeni bir secret key oluştur'a basın, eskisi hemen çalışmayı durdurur. Bazı SDK'lar ayrıca aynı sayfada gösterilen proje id'sine ihtiyaç duyar.

app.blipit.io'da API anahtarları: tarayıcı kodu için public key (blipit_pk_), sunucular ve Odoo için secret key (blipit_sk_).
app.blipit.io'da API anahtarları: tarayıcı kodu için public key (blipit_pk_), sunucular ve Odoo için secret key (blipit_sk_).
Yeni bir secret key yalnızca bir kez gösterilir. Şimdi kopyalayın: hash'lenmiş olarak saklanır ve bir daha gösterilemez.
Yeni bir secret key yalnızca bir kez gösterilir. Şimdi kopyalayın: hash'lenmiş olarak saklanır ve bir daha gösterilemez.

3Anahtarları .env.local içine koyun

Proje kök dizininde, tarayıcı için public key'i ve aşağıdaki sunucu tarafını kullanıyorsanız sunucu için secret key'i içeren .env.local dosyasını oluşturun. Tarayıcıya yalnızca NEXT_PUBLIC_ ile başlayan adlar ulaşır; bu yüzden secret key'e asla bu öneki vermeyin. Dosyayı kaydettikten sonra npm run dev'i yeniden başlatın. Production için aynı değişkenleri barındırma ortamınıza ekleyin (Vercel'de: Project, Settings, Environment Variables, Production ve Preview için) ve yeniden deploy edin: NEXT_PUBLIC_ değerleri build'e yazılır, bu yüzden onları eklemeden önce yapılmış bir deployment'ın anahtarı boştur.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4Tarayıcı tarafı

Bileşeni kök layout'a bir kez ekleyin. Public key'i NEXT_PUBLIC_BLIPIT_KEY'den okur. Değişken boşsa hiçbir şey başlatmaz ve bunu tarayıcı konsolunda belirtir.

app/layout.tsx
import { Blipit } from "@blipit/nextjs";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Blipit
          publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
          environment={process.env.NEXT_PUBLIC_VERCEL_ENV ?? "development"}
          release={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA}
          replay={{ onErrorSampleRate: 1 }}
        />
        {children}
      </body>
    </html>
  );
}

5Sunucu tarafı

Next.js 15 ve sonrası, server component, route handler ve server action hataları için onRequestError'ı çağırır. instrumentation.ts içindeki tek satır bunu Blipit'e bağlar. @blipit/nextjs 0.2.1 sürümünden itibaren aynı satır middleware.ts bulunan uygulamalarda ve Edge rotalarında (runtime = "edge") da çalışır: uygulama derlenir, middleware ve Edge hataları da bildirilir. Next.js 14'te onRequestError yoktur; bu yüzden ikinci örnekteki gibi her route handler ve server action'ı withBlipit ile sarın: hatayı bildirir, yeniden fırlatır ve yönlendirmeleri ile notFound()'u atlar. BLIPIT_SECRET_KEY'i sunucu ortamında ayarlayın, asla NEXT_PUBLIC_ olarak değil.

instrumentation.ts
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";
app/api/orders/route.ts
import { withBlipit } from "@blipit/nextjs/server";

export const GET = withBlipit(async (request: Request) => {
  return Response.json(await loadOrders());
});

6Bağımlılıklar ve sunucu sağlığı

@blipit/nextjs 0.3'ten itibaren register'ı da dışa aktarın; böylece Blipit sunucu açılırken başlar. Ardından veritabanı ve dış hizmet çağrıları Bağımlılıklar sayfasında, sunucunun CPU, bellek ve olay döngüsü Sunucu sağlığı sayfasında görünür. Edge çalışma zamanında hiçbir şey yapmaz. Vercel'de register gelen isteği göremeyebilir: @blipit/nextjs 0.4'ten itibaren route handler ve server action'ları withBlipit ile sarmalayın; her biri veritabanı ve dış hizmet çağrılarıyla birlikte Pulse sayfasında bir istek olur ve yanıttan sonra, onu geciktirmeden gönderilir.

instrumentation.ts
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";
app/api/orders/route.ts
import { withBlipit } from "@blipit/nextjs/server";

export const GET = withBlipit(async (request: Request) => Response.json(await loadOrders()));

7error.tsx tarafından yakalanan hatalar

Bir error.tsx ya da global-error.tsx sınırının yakaladığı hatalar tarayıcının hata handler'ına hiç ulaşmaz, bu yüzden onları sınırın içinden raporlayın. Her iki dosya da client component'tir.

app/error.tsx
"use client";

import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";

export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
    captureException(error);
  }, [error]);
  return (
    <div>
      <p>Something went wrong.</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}
app/global-error.tsx
"use client";

import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => {
    captureException(error);
  }, [error]);
  return (
    <html>
      <body>
        <p>Something went wrong.</p>
      </body>
    </html>
  );
}

8Anahtarları git'ten uzak tutun

Anahtarları ortam değişkenlerinde ya da barındırma ortamınızın gizli ayarlarında tutun, asla commit ettiğiniz kodda tutmayın ve .env dosyalarınızı .gitignore'a ekleyin. Bir web sayfasında public key bulunması normaldir. Bir secret key git'e, herkese açık bir sayfaya, bir ekran görüntüsüne ya da bir sohbete düşerse API anahtarları'nı açın, Yeni bir secret key oluştur'a basın ve yeni anahtarı eskisinin kullanıldığı her yere yapıştırın: eski anahtar hemen çalışmayı durdurur.

.gitignore
.env
.env.local
.env.*.local

9Content Security Policy

Siteniz bir Content Security Policy gönderiyorsa script-src https://blipit.io (script etiketi ile ilk kullanımda blipit.io/sdk/<version>/ adresinden yüklenen bildirim düzenleyicisi ve replay eklentisi), connect-src https://in.blipit.io (olaylar, ekran görüntüleri ve ekran kayıtlarının hepsi in.blipit.io adresine gider), img-src data: (ekran görüntüsü sayfanın bir görüntüsünden çizilir) ve media-src blob: (kayıtlar bildirim penceresinde oynatılır) izinlerini verin. Ekran görüntüsü sayfanın görsellerini ve yazı tiplerini yeniden yükler; bu yüzden onların sunucuları da connect-src içinde olmalıdır, yoksa boş kalırlar. style-src'de değişiklik gerekmez. Script etiketiyle Blipit.init'i kendi .js dosyanızdan çağırın ya da satır içi scripte bir nonce verin, çünkü katı bir politika satır içi scriptleri engeller. Ekran kayıtlarında ses olması için sitenizin Permissions-Policy başlığı microphone=(self) değerine, ekran kaydı için de display-capture=(self) değerine izin vermelidir; microphone=() ile kayıtlar sessiz çalışır.

10Source map'ler (isteğe bağlı)

Stack trace'lerin küçültülmüş bundle yerine kaynağınızı göstermesi için her release'in map'lerini build adımınızdan yükleyin.

sh
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"

11Hata raporları: Hata bildir düğmesi

SDK public key'inizle başlar başlamaz, her sayfanın sağ alt köşesinde ziyaretçinin dilinde bir Hata bildir düğmesi görünür. Bir tıklama bildirim formunu açar: işaretlenecek bir sayfa ekran görüntüsü, bir öğe seçici, isteğe bağlı bir ekran kaydı, bir başlık ve açıklama. Konumu, stili, metni, rengi ve klavye kısayolunu aşağıdaki gibi kodda ya da tüm siteler için tek seferde app.blipit.io'da Proje ayarları, Hata raporu widget'ı altında değiştirin; koddaki seçenekler önceliklidir. Hata bildir düğmesi kılavuzu her seçeneği ekran görüntüleri ve canlı bir demoyla gösterir.

app/layout.tsx
<Blipit
  publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
  feedbackWidget={{
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  }}
/>
Sağ alttaki varsayılan Hata bildir düğmesi.
Sağ alttaki varsayılan Hata bildir düğmesi.
Bildirim formu: işaretlenmiş bir ekran görüntüsü, başlık ve ne olduğu.
Bildirim formu: işaretlenmiş bir ekran görüntüsü, başlık ve ne olduğu.

12Bildirim formunu kendi düğmenizden açın

Resmi düğmeyi <BlipitReportButton /> ile her yere koyun, server component'lerde de: Blipit simgesini ve ziyaretçinin dilinde Hata bildir yazısını gösterir ve bildirim penceresini açar. Kendi tasarımınızı mı tercih edersiniz? openReport çağıran bileşen bir client component olmalıdır, bu yüzden dosyasının en üstüne "use client" yazın. <Blipit /> zaten app/layout.tsx içinde olmalıdır. Next.js kullanmayan React uygulamaları düğmeyi @blipit/nextjs/react, openReport'u ise @blipit/browser içinden içe aktarır.

app/header.tsx
import { BlipitReportButton } from "@blipit/nextjs";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
Next.js olmadan React
import { BlipitReportButton } from "@blipit/nextjs/react";

<BlipitReportButton variant="outline" size="sm" />
app/report-issue.tsx
"use client";

import { openReport } from "@blipit/nextjs";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
React (@blipit/browser)
import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
Bir sitenin başlığında resmi Hata bildir düğmesi.
Bir sitenin başlığında resmi Hata bildir düğmesi.
Bir Next.js uygulaması: başlıktaki özel Report Issue düğmesi Blipit bildirim formunu açtı.
Bir Next.js uygulaması: başlıktaki özel Report Issue düğmesi Blipit bildirim formunu açtı.

13Varsayılan düğmeyi gizleyin

Yalnızca kendi düğmenizi bırakmak için yüzen düğmeyi kodda feedbackWidget: false ile (<Blipit /> üzerinde feedbackWidget={false}) kapatın ya da anahtarı kullanan her sitede gizlemek için projenin Hata raporu widget'ı ayarlarında Hata raporu düğmesini göster'i kapatın. openReport() ve attachReport() her iki durumda da çalışmaya devam eder.

app/layout.tsx
<Blipit publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!} feedbackWidget={false} />

14Bildirim formunu önceden doldurun ve bağlam ekleyin

Girişten sonra setUser'ı çağırın: bildiren kişinin adı ve e-postası doldurulur ve yanıt verdiğinizde ya da durumu değiştirdiğinizde e-posta alır. setReportMetadata, plan ya da sepet büyüklüğü gibi kendi alanlarınızı her bildirime ekler; bildirim gönderildiğinde çalıştığı için değerler günceldir.

app/blipit-user.tsx
"use client";

import { useEffect } from "react";
import { setReportMetadata, setUser } from "@blipit/nextjs";

export function BlipitUser({ user }: { user: { id: string; name: string; email: string; plan: string } }) {
  useEffect(() => {
    setUser({ id: user.id, username: user.name, email: user.email });
    setReportMetadata(() => ({ plan: user.plan }));
  }, [user]);
  return null;
}

15Çalıştığını kontrol edin

Uygulamayı yeniden yükleyin. Hata bildir düğmesi sağ alt köşede görünür ve bir dakika içinde sayfa görüntülemesi app.blipit.io'da Web vitals altında görünür. Ardından captureMessage çağıran ya da hata fırlatan bir düğme ekleyip tıklayın: olay birkaç saniye içinde Sorunlar altında görünür.

tsx
"use client";
import { captureMessage } from "@blipit/nextjs";

export function TestBlipit() {
  return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}

16Düğme ya da olaylar görünmüyorsa

  • Tarayıcı konsolunu açın ve [blipit] ile başlayan satırlara bakın. Düğmenin gösterilip gösterilmediğini, kodda kapatılıp kapatılmadığını ya da proje ayarıyla gizlenip gizlenmediğini görmek için debug'ı açın (init içinde debug: true ya da <Blipit /> üzerinde debug).
  • Next.js tarayıcıya yalnızca adı NEXT_PUBLIC_ ile başlayan değişkenleri gönderir, bu yüzden NEXT_PUBLIC_BLIPIT_KEY kullanın. Vite yalnızca VITE_ değişkenlerini gönderir, bu yüzden VITE_BLIPIT_KEY kullanın. Başka bir adla anahtar tarayıcıda boş olur ve Blipit başlamaz.
  • .env ya da .env.local dosyasını ekledikten veya değiştirdikten sonra dev sunucusunu yeniden başlatın. Sunucu bunları yalnızca başlarken okur.
  • Vercel'de ya da başka bir barındırma ortamında aynı değişkeni projenin ortam değişkenlerine ekleyin ve yeniden deploy edin. NEXT_PUBLIC_ ve VITE_ değerleri build'e yazılır, bu yüzden çalışan bir deployment sonradan eklenen bir değeri asla görmez.
  • Public key'i (blipit_pk_) kullanın. Secret key (blipit_sk_) tarayıcıda bir konsol hatasıyla reddedilir; bir secret key bir sayfada bulunduysa yeni bir secret key oluşturun.
  • Next.js'te <Blipit />, her sayfada çalışması için kök app/layout.tsx (ya da pages/_app.tsx) dosyasına konur. Diğer uygulamalarda init'i giriş dosyasında, uygulama render edilmeden önce bir kez çağırın.
  • app.blipit.io'da Proje ayarları, Hata raporu widget'ı altında Hata raporu düğmesini göster açık olmalı ve kodunuz feedbackWidget: false geçirmemelidir. SDK proje ayarlarını en fazla bir saat saklar, bu yüzden bir değişikliği gizli bir pencerede test edin.
  • Reklam engelleyiciler ve gizlilik eklentileri in.blipit.io'yu engelleyebilir. Eklentiler kapalıyken gizli bir pencerede deneyin.
  • Siteniz bir Content Security Policy gönderiyorsa script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: ve media-src blob: izinlerini verin. Bildirim düzenleyicisi ilk tıklamada blipit.io/sdk adresinden yüklenir, ekran görüntüsü bir data: görüntüsünden çizilir ve ekran kayıtları da in.blipit.io adresine yüklenir. debug açıkken konsol, politikanın ekran görüntüsünü ne zaman engellediğini söyler. Ekran kayıtlarında ses olması için sitenizin Permissions-Policy başlığı microphone=(self) değerine, ekran kaydı için de display-capture=(self) değerine izin vermelidir; microphone=() ile kayıtlar sessiz çalışır.
  • Kurulu sürümü npm ls @blipit/browser @blipit/nextjs (veya pnpm list @blipit/browser @blipit/nextjs) ile kontrol edin ve değişiklik günlüğüyle karşılaştırın. pnpm 11 yeni bir sürümü kurmadan önce bir gün bekler (minimum-release-age), bu yüzden yayın günü pnpm add hiçbir uyarı vermeden önceki sürümü kurar. Yenisini hemen almak için: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Hâlâ takıldınız mı? Konsoldaki [blipit] satırlarıyla birlikte support@blipit.io adresine e-posta gönderin.

Bilmekte fayda var

  • Next.js olmadan düz React: npm install @blipit/browser çalıştırın ve render'dan önce Blipit.init'i çağırın; bkz. Herhangi bir web sitesi.
  • Boş bıraktığınızda ortam ve release, sunucuda varsayılan olarak VERCEL_ENV ve VERCEL_GIT_COMMIT_SHA değerlerini alır.
  • Blipit'i güncel tutmak: Blipit'i güncel tutmak rehberi (docs.blipit.io/updates) güncelleme afişini, önemli sürümler için e-postaları, geliştirme konsolunuzdaki bildirimi ve bu platformun güncelleme komutunu açıklar.
  • Her uygulama ve platform için bir proje: her proje oluşturulurken platformunu seçer (Android, iOS, React Native, Flutter, Web, Backend veya Odoo) ve Blipit başka bir platformdan gelen verileri açık bir hatayla reddeder. Yani bir iOS uygulaması ile bir Android uygulaması için iki anahtarlı iki proje gerekir. Sürümler, versiyonlar, çökme oranları ve mağaza derlemeleri her platformda farklıdır; bunları tek projede karıştırmak hepsini yanlış yapar. Web projesi aynı web uygulamasının sunucu tarafını da kabul eder (Next.js sunucusu veya Node), React Native veya Flutter projesi de kendi yerel Android ve iOS çökme raporlarını kabul eder.

Takıldınız mı? support@blipit.io adresine e-posta gönderin. Her projenin anahtarları ve proje id'si app.blipit.io içindeki API anahtarları altındadır.