Instalación - Next.js

Antes de empezar, crea un proyecto en el panel de DockRay. En sus ajustes encontrarás el token del proyecto - el identificador público que forma parte de la URL de ingesta - y en la pestaña Claves de API generarás una clave privada. La clave se muestra una sola vez, al generarla: DockRay guarda únicamente su hash. Si todavía no tienes un proyecto, empieza por Primeros pasos.

Requisitos

• Next.js 14 o 15, App Router o Pages Router,
• Node.js 18 o posterior - la integración usa el fetch integrado,
• npm.

Instalar el paquete

npm install @dockcodes/dock-ray-next

Credenciales

RAY_TOKEN=token-del-proyecto
RAY_PRIVATE_KEY=clave-privada-del-proyecto
RAY_URL=https://dockray.io
RAY_TRACES_SAMPLE_RATE=0.2

RAY_PRIVATE_KEY no debe llevar nunca el prefijo NEXT_PUBLIC_ - y no es una cuestión de estilo. Next incrusta cualquier variable con ese prefijo directamente en el paquete que llega al navegador, así que la clave privada se volvería pública en el momento del build. Sin RAY_TOKEN ni RAY_PRIVATE_KEY la integración permanece inactiva - ni peticiones ni errores - así que puedes conectarla una vez y no envolverla nunca en una condición.

Notificación de errores del servidor

En instrumentation.ts, en la raíz del proyecto:

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

export function register() {
    initRay();
}

export const onRequestError = rayRequestError();

onRequestError es el único hook que ve todos los errores que Next captura - de Server Components, Route Handlers, Server Actions y renderizados en streaming. Next lo llama cuando la respuesta ya ha fallado, así que notificar nunca retrasa una petición. Cada aviso lleva el contexto de la ruta como etiqueta (router, route, route_type, render_source), lo que permite ver en el panel de dónde vino realmente el error.

Middleware y Edge Runtime

Next siempre construye el middleware como un paquete de edge, y un paquete de edge no puede resolver node:fs ni node:zlib. El middleware y las rutas de edge importan un punto de entrada distinto:

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

initRay();

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

Los eventos de edge pierden el contexto de origen en la pila y la compresión gzip - lo demás no cambia. El wrapper de edge espera a que se envíe el informe en lugar de dispararlo y olvidarse: una invocación de edge puede congelarse en el momento en que la función devuelve el resultado, así que un envío a medias podría no salir nunca.

Pages Router y rutas de API

onRequestError cubre el App Router. Para el Pages Router, o donde quieras marcar un error explícitamente como propio, usa el 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 notifica el error y lo vuelve a lanzar - nunca lo silencia, así que tu propio manejo de errores sigue funcionando.

La primera prueba

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

await getRay().captureMessage('Mensaje de control DockRay');

Llama a esto desde una ruta temporal o una Server Action en un entorno de pruebas. El mensaje debería aparecer en el panel, en la sección Errores del proyecto al que apunta el token.