Next.js und React

Installation npm install @blipit/nextjs

@blipit/nextjs liefert Ihnen Browser-Fehler, Web Vitals, Session Replay und den Button Fehler melden über eine einzige Komponente in Ihrem Layout, und Fehler aus Server Components, Route Handlern und Server Actions über eine einzige Zeile in instrumentation.ts. Reine React-Apps verwenden @blipit/browser.

Fügen Sie ihn in Claude Code, Cursor oder einen anderen KI-Programmierassistenten ein. Er enthält die Schritte und den Code. In app.blipit.io unter API-Schlüssel steht derselbe Prompt mit Ihrem Schlüssel bereits eingetragen.
Video: Blipit in jedem Stack installieren, ab 0:32

1Installation

sh
npm install @blipit/nextjs

2Schlüssel abrufen

Melden Sie sich bei app.blipit.io an und öffnen Sie API-Schlüssel in der Seitenleiste, dann Ihr Projekt. Jedes Projekt hat zwei Schlüssel. Der öffentliche Schlüssel beginnt mit blipit_pk_: Er gehört in Browser- und App-Code, kann nur Events senden und darf von jedem gesehen werden. Der geheime Schlüssel beginnt mit blipit_sk_: Er bleibt auf Ihrem Server oder in Odoo, nie in einem Browser, weil er auch Issues lesen und ändern kann. Der geheime Schlüssel wird nur einmal angezeigt, direkt nach der Erstellung, kopieren Sie ihn also dann; geht er verloren, klicken Sie auf Neuen geheimen Schlüssel erstellen, und der alte funktioniert sofort nicht mehr. Manche SDKs brauchen zusätzlich die Projekt-ID, die auf derselben Seite steht.

API-Schlüssel in app.blipit.io: der öffentliche Schlüssel (blipit_pk_) für Browser-Code und der geheime Schlüssel (blipit_sk_) für Server und Odoo.
API-Schlüssel in app.blipit.io: der öffentliche Schlüssel (blipit_pk_) für Browser-Code und der geheime Schlüssel (blipit_sk_) für Server und Odoo.
Ein neuer geheimer Schlüssel wird einmal angezeigt. Kopieren Sie ihn sofort: Er wird gehasht gespeichert und kann nicht erneut angezeigt werden.
Ein neuer geheimer Schlüssel wird einmal angezeigt. Kopieren Sie ihn sofort: Er wird gehasht gespeichert und kann nicht erneut angezeigt werden.

3Die Schlüssel in .env.local ablegen

Legen Sie im Projektstamm .env.local an, mit dem öffentlichen Schlüssel für den Browser und, falls Sie die Serverseite unten nutzen, dem geheimen Schlüssel für den Server. Nur Namen, die mit NEXT_PUBLIC_ beginnen, erreichen den Browser, geben Sie dem geheimen Schlüssel dieses Präfix also nie. Starten Sie npm run dev nach dem Speichern der Datei neu. Für die Produktion fügen Sie dieselben Variablen bei Ihrem Hoster hinzu (auf Vercel: Project, Settings, Environment Variables, für Production und Preview) und deployen erneut: NEXT_PUBLIC_-Werte werden in den Build geschrieben, daher hat ein Deployment, das vor dem Hinzufügen erstellt wurde, einen leeren Schlüssel.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4Browserseite

Fügen Sie die Komponente einmal im Root-Layout ein. Sie liest den öffentlichen Schlüssel aus NEXT_PUBLIC_BLIPIT_KEY. Ist die Variable leer, startet sie nichts und meldet das in der Browser-Konsole.

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>
  );
}

5Serverseite

Next.js 15 und neuer rufen onRequestError bei Fehlern in Server Components, Route Handlers und Server Actions auf. Eine Zeile in instrumentation.ts verbindet es mit Blipit. Ab @blipit/nextjs 0.2.1 funktioniert dieselbe Zeile auch in Apps mit einer middleware.ts und in Edge-Routen (runtime = "edge"): Die App lässt sich bauen, und Fehler aus Middleware und Edge werden ebenfalls gemeldet. Next.js 14 hat kein onRequestError; umschließen Sie dort jeden Route Handler und jede Server Action mit withBlipit, wie im zweiten Beispiel: Es meldet den Fehler, wirft ihn erneut und lässt Redirects und notFound() aus. Setzen Sie BLIPIT_SECRET_KEY in der Server-Umgebung, nie als NEXT_PUBLIC_.

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());
});

6Abhängigkeiten und Serverzustand

Ab @blipit/nextjs 0.3 exportierst du auch register, damit Blipit beim Serverstart beginnt. Dann erscheinen Datenbank- und externe Aufrufe unter Abhängigkeiten und CPU, Speicher und Event-Loop des Servers unter Serverzustand. In der Edge-Runtime tut es nichts. Auf Vercel sieht register die eingehende Anfrage womöglich nicht: Ab @blipit/nextjs 0.4 umschließen Sie Route Handler und Server Actions mit withBlipit, dann wird jeder zu einer Anfrage auf der Seite Pulse mit ihren Datenbank- und externen Aufrufen, gesendet nach der Antwort, ohne sie zu verzögern.

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()));

7Von error.tsx abgefangene Fehler

Fehler, die eine error.tsx- oder global-error.tsx-Boundary abfängt, erreichen den Fehler-Handler des Browsers nie, melden Sie sie daher aus der Boundary. Beide Dateien sind Client Components.

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>
  );
}

8Schlüssel aus Git heraushalten

Bewahren Sie Schlüssel in Umgebungsvariablen oder den Secret-Einstellungen Ihres Hosters auf, nie in Code, den Sie committen, und tragen Sie Ihre .env-Dateien in .gitignore ein. Ein öffentlicher Schlüssel in einer Webseite ist normal. Landet ein geheimer Schlüssel je in Git, auf einer öffentlichen Seite, in einem Screenshot oder einem Chat, öffnen Sie API-Schlüssel, klicken Sie auf Neuen geheimen Schlüssel erstellen und fügen Sie den neuen Schlüssel überall ein, wo der alte verwendet wurde: Der alte Schlüssel funktioniert sofort nicht mehr.

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

9Content Security Policy

Wenn Ihre Website eine Content Security Policy sendet, erlauben Sie script-src https://blipit.io (das Script-Tag sowie den Reporter-Editor und das Replay-Add-on, die beim ersten Gebrauch von blipit.io/sdk/<version>/ geladen werden), connect-src https://in.blipit.io (Ereignisse, Screenshots und Bildschirmaufnahmen gehen alle an in.blipit.io), img-src data: (der Screenshot wird aus einem Bild der Seite gezeichnet) und media-src blob: (Aufnahmen werden im Reporter abgespielt). Der Screenshot lädt die Bilder und Schriften der Seite neu, daher gehören deren Hosts ebenfalls in connect-src, sonst bleiben sie leer. Eine Änderung an style-src ist nicht nötig. Rufen Sie beim Script-Tag Blipit.init aus einer eigenen .js-Datei auf oder geben Sie dem Inline-Script eine Nonce, denn eine strenge Policy blockiert Inline-Scripts. Damit Bildschirmaufnahmen Ton enthalten, muss der Permissions-Policy-Header Ihrer Website microphone=(self) erlauben, für die Bildschirmaufnahme außerdem display-capture=(self); mit microphone=() funktionieren Aufnahmen ohne Ton.

10Source Maps (optional)

Damit Stack Traces Ihren Quellcode statt des minifizierten Bundles zeigen, laden Sie die Maps für jedes Release aus Ihrem Build-Schritt hoch.

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

11Fehlerberichte: der Button Fehler melden

Sobald das SDK mit Ihrem öffentlichen Schlüssel startet, erscheint unten rechts auf jeder Seite ein Button Fehler melden, in der Sprache des Besuchers. Ein Klick öffnet den Reporter: einen Screenshot der Seite zum Markieren, eine Elementauswahl, eine optionale Bildschirmaufnahme sowie Titel und Beschreibung. Position, Stil, Text, Farbe und Tastenkürzel ändern Sie wie unten im Code oder für alle Websites auf einmal in app.blipit.io unter Projekteinstellungen, Fehlerbericht-Widget; Optionen im Code haben Vorrang. Die Anleitung zum Fehlerbericht-Button zeigt jede Option mit Screenshots und einer Live-Demo.

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",
  }}
/>
Der Standard-Button Fehler melden, unten rechts.
Der Standard-Button Fehler melden, unten rechts.
Der Reporter: ein markierter Screenshot, der Titel und was passiert ist.
Der Reporter: ein markierter Screenshot, der Titel und was passiert ist.

12Den Reporter über Ihren eigenen Button öffnen

Setzen Sie den offiziellen Button mit <BlipitReportButton /> an eine beliebige Stelle, auch in Server Components: Er zeigt das Blipit-Symbol und Fehler melden in der Sprache der Besucher und öffnet den Reporter. Lieber ein eigenes Design? Die Komponente, die openReport aufruft, muss eine Client Component sein, setzen Sie also "use client" an den Anfang ihrer Datei. <Blipit /> muss bereits in app/layout.tsx stehen. Reine React-Apps importieren den Button aus @blipit/nextjs/react und openReport aus @blipit/browser.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
React ohne Next.js
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>;
}
Der offizielle Button Fehler melden im Header einer Website.
Der offizielle Button Fehler melden im Header einer Website.
Eine Next.js-App: Der eigene Button Report Issue im Header hat den Blipit-Reporter geöffnet.
Eine Next.js-App: Der eigene Button Report Issue im Header hat den Blipit-Reporter geöffnet.

13Den Standard-Button ausblenden

Um nur Ihren eigenen Button zu behalten, schalten Sie den schwebenden mit feedbackWidget: false im Code aus (feedbackWidget={false} an <Blipit />), oder deaktivieren Sie Fehlerbericht-Button anzeigen in den Fehlerbericht-Widget-Einstellungen des Projekts, um ihn auf jeder Website auszublenden, die den Schlüssel nutzt. openReport() und attachReport() funktionieren in beiden Fällen weiter.

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

14Den Reporter vorausfüllen und Kontext hinzufügen

Rufen Sie setUser nach der Anmeldung auf: Name und E-Mail der meldenden Person werden vorausgefüllt, und sie erhält eine E-Mail, wenn Sie antworten oder den Status ändern. setReportMetadata fügt jedem Bericht eigene Felder hinzu, etwa den Plan oder die Warenkorbgröße; die Funktion läuft beim Senden eines Berichts, daher sind die Werte aktuell.

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;
}

15Prüfen, ob es funktioniert

Laden Sie die App neu. Der Button Fehler melden erscheint unten rechts, und innerhalb einer Minute erscheint der Seitenaufruf unter Web Vitals in app.blipit.io. Fügen Sie dann einen Button hinzu, der captureMessage aufruft oder einen Fehler wirft, und klicken Sie darauf: Das Event erscheint innerhalb weniger Sekunden unter Issues.

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

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

16Wenn der Button oder die Events nicht erscheinen

  • Öffnen Sie die Browser-Konsole und suchen Sie nach Zeilen, die mit [blipit] beginnen. Schalten Sie debug ein (debug: true in init oder debug an <Blipit />), um zu sehen, ob der Button angezeigt, im Code ausgeschaltet oder durch die Projekteinstellung ausgeblendet wurde.
  • Next.js sendet nur Variablen, deren Namen mit NEXT_PUBLIC_ beginnen, an den Browser, verwenden Sie daher NEXT_PUBLIC_BLIPIT_KEY. Vite sendet nur VITE_-Variablen, verwenden Sie daher VITE_BLIPIT_KEY. Mit jedem anderen Namen ist der Schlüssel im Browser leer, und Blipit startet nicht.
  • Starten Sie den Dev-Server neu, nachdem Sie .env oder .env.local hinzugefügt oder geändert haben. Er liest sie nur beim Start.
  • Fügen Sie auf Vercel oder bei jedem anderen Hoster dieselbe Variable in den Umgebungsvariablen des Projekts hinzu und deployen Sie erneut. NEXT_PUBLIC_- und VITE_-Werte werden in den Build geschrieben, daher sieht ein laufendes Deployment einen später hinzugefügten Wert nie.
  • Verwenden Sie den öffentlichen Schlüssel (blipit_pk_). Ein geheimer Schlüssel (blipit_sk_) wird im Browser mit einem Konsolenfehler abgelehnt; war einer je auf einer Seite, erstellen Sie einen neuen geheimen Schlüssel.
  • In Next.js gehört <Blipit /> in das Root-Layout app/layout.tsx (oder pages/_app.tsx), damit es auf jeder Seite läuft. In anderen Apps rufen Sie init einmal in der Einstiegsdatei auf, bevor die App rendert.
  • Fehlerbericht-Button anzeigen muss in app.blipit.io unter Projekteinstellungen, Fehlerbericht-Widget eingeschaltet sein, und Ihr Code darf nicht feedbackWidget: false übergeben. Das SDK speichert die Projekteinstellungen bis zu einer Stunde, testen Sie eine Änderung daher in einem privaten Fenster.
  • Werbeblocker und Datenschutz-Erweiterungen können in.blipit.io blockieren. Versuchen Sie es in einem privaten Fenster mit deaktivierten Erweiterungen.
  • Wenn Ihre Website eine Content Security Policy sendet, erlauben Sie script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: und media-src blob:. Der Reporter-Editor wird beim ersten Klick von blipit.io/sdk geladen, der Screenshot wird aus einem data:-Bild gezeichnet, und Bildschirmaufnahmen werden ebenfalls zu in.blipit.io hochgeladen. Mit debug zeigt die Konsole an, wenn die Policy den Screenshot blockiert hat. Damit Bildschirmaufnahmen Ton enthalten, muss der Permissions-Policy-Header Ihrer Website microphone=(self) erlauben, für die Bildschirmaufnahme außerdem display-capture=(self); mit microphone=() funktionieren Aufnahmen ohne Ton.
  • Prüfen Sie die installierte Version mit npm ls @blipit/browser @blipit/nextjs (oder pnpm list @blipit/browser @blipit/nextjs) und vergleichen Sie sie mit dem Changelog. pnpm 11 wartet einen Tag, bevor es eine neue Version installiert (minimum-release-age), daher installiert pnpm add am Veröffentlichungstag stillschweigend die vorherige Version. So erhalten Sie die neue sofort: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Kommen Sie nicht weiter? Schreiben Sie an support@blipit.io und fügen Sie die [blipit]-Zeilen aus der Konsole bei.

Gut zu wissen

  • Reines React ohne Next.js: npm install @blipit/browser und Blipit.init vor dem Rendern aufrufen; siehe Beliebige Website.
  • Umgebung und Release fallen auf dem Server auf VERCEL_ENV und VERCEL_GIT_COMMIT_SHA zurück, wenn Sie sie weglassen.
  • Blipit aktuell halten: Die Anleitung „Blipit auf dem neuesten Stand halten“ (docs.blipit.io/updates) erklärt das Update-Banner, die E-Mails zu wichtigen Releases, den Hinweis in deiner Entwicklungskonsole und den Update-Befehl für diese Plattform.
  • Ein Projekt pro App und Plattform: Jedes Projekt legt beim Anlegen seine Plattform fest (Android, iOS, React Native, Flutter, Web, Backend oder Odoo), und Blipit lehnt Daten von jeder anderen Plattform mit einer klaren Fehlermeldung ab. Eine iOS-App und eine Android-App brauchen also zwei Projekte mit zwei Schlüsseln. Releases, Versionen, Absturzraten und Store-Builds sind je Plattform verschieden, und gemischt in einem Projekt stimmt keiner dieser Werte mehr. Ein Web-Projekt nimmt auch die Serverseite derselben Web-App an (den Next.js-Server oder Node), und ein React-Native- oder Flutter-Projekt auch seine eigenen nativen Android- und iOS-Absturzberichte.

Kommen Sie nicht weiter? Schreiben Sie an support@blipit.io. Schlüssel und die Projekt-ID jedes Projekts finden Sie unter API-Schlüssel in app.blipit.io.