Installation - Next.js

Erstelle zuerst ein Projekt im DockRay-Panel. In seinen Einstellungen findest du den Projekt-Token - die öffentliche Kennung, die in die Ingest-URL eingeht - und im Tab API-Schlüssel erzeugst du einen privaten Schlüssel. Der Schlüssel wird nur einmal angezeigt, beim Erzeugen: DockRay speichert lediglich seinen Hash. Wenn noch kein Projekt existiert, beginne mit Erste Schritte.

Voraussetzungen

• Next.js 14 oder 15, App Router oder Pages Router,
• Node.js 18 oder neuer - die Integration nutzt das eingebaute fetch,
• npm.

Paket installieren

npm install @dockcodes/dock-ray-next

Zugangsdaten

RAY_TOKEN=projekt-token
RAY_PRIVATE_KEY=privater-projektschluessel
RAY_URL=https://dockray.io
RAY_TRACES_SAMPLE_RATE=0.2

RAY_PRIVATE_KEY darf niemals den Präfix NEXT_PUBLIC_ bekommen - das ist keine Stilfrage. Next bettet jede Variable mit diesem Präfix direkt in das Bundle ein, das an den Browser geht, der private Schlüssel wäre also mit dem Build öffentlich. Ohne RAY_TOKEN und RAY_PRIVATE_KEY bleibt die Integration untätig - keine Anfragen, keine Fehler - du kannst sie also einmal einbinden und musst sie nie in eine Bedingung kapseln.

Serverfehler melden

In instrumentation.ts im Projektstamm:

import { initRay, rayRequestError } from '@dockcodes/dock-ray-next';

export function register() {
    initRay();
}

export const onRequestError = rayRequestError();

onRequestError ist der einzige Hook, der jeden von Next abgefangenen Fehler sieht - aus Server Components, Route Handlers, Server Actions und Streaming-Renderings. Next ruft ihn erst auf, nachdem die Antwort bereits fehlgeschlagen ist, das Melden verzögert also nie eine Anfrage. Jede Meldung wird mit dem Routenkontext getaggt (router, route, route_type, render_source), wodurch das Panel zeigt, woher ein Fehler wirklich kam.

Middleware und die Edge Runtime

Next baut Middleware immer als Edge-Bundle, und ein Edge-Bundle kann node:fs oder node:zlib nicht auflösen. Middleware und Edge-Routen importieren einen eigenen Einstiegspunkt:

import { initRay, withRayMiddleware } from '@dockcodes/dock-ray-next/edge';

initRay();

export const middleware = withRayMiddleware(async (request) => {
    // ...
});

Edge-Ereignisse verlieren den Quellkontext im Stacktrace und die gzip-Kompression - sonst ändert sich nichts. Der Edge-Wrapper wartet auf seinen Report, statt ihn abzufeuern und zu vergessen: ein Edge-Aufruf kann in dem Moment eingefroren werden, in dem die Funktion zurückkehrt, ein unfertiger Versand käme dann vielleicht nie hinaus.

Pages Router und API-Routen

onRequestError deckt den App Router ab. Für den Pages Router, oder überall dort, wo ein Fehler ausdrücklich als eigener markiert werden soll, nimm den Wrapper:

import { withRay } from '@dockcodes/dock-ray-next';

export default withRay(async function handler(req, res) {
    const order = await processOrder(req.body);

    res.status(200).json({ success: true, order });
});

withRay meldet den Fehler und wirft ihn weiter - es verschluckt ihn nie, deine eigene Fehlerbehandlung läuft also weiter.

Der erste Test

import { getRay } from '@dockcodes/dock-ray-next';

await getRay().captureMessage('DockRay-Kontrollmeldung');

Rufe das aus einer temporären Route oder einer Server Action in einer Staging-Umgebung auf. Die Meldung sollte im Panel unter Fehler des Projekts erscheinen, auf das der Token zeigt.