Configuración - Next.js

3 min de lectura Actualizado: 11.09.2026

Variables de entorno

La integración no tiene archivo de configuración propio: todo se lee del entorno cuando se ejecuta initRay().

Variable	Por defecto	Significado
`RAY_TOKEN`, `RAY_PRIVATE_KEY`	-	credenciales del proyecto; sin ambas la integración permanece en silencio
`RAY_URL`	`https://dockray.io`	instancia de DockRay
`RAY_ENVIRONMENT`	`VERCEL_ENV`, luego `NODE_ENV`	columna de entorno en el panel
`RAY_RELEASE`	`VERCEL_GIT_COMMIT_SHA`	versión de la aplicación desplegada
`RAY_SAMPLE_RATE`	`1`	proporción de eventos de error enviados
`RAY_TRACES_SAMPLE_RATE`	`0`	proporción de transacciones enviadas; `0` desactiva la medición
`RAY_SEND_DEFAULT_PII`	`false`	adjunta la IP y el user agent del visitante

Entornos

Cada entorno debería informar con un nombre inequívoco: production, staging, preview. El nombre es una columna del panel y un filtro de la lista de errores, así que sin él una caída de producción se ve igual que un error provocado en una prueba. Deja el entorno local sin credenciales: sin token ni clave la integración se carga y permanece en silencio, de modo que no necesitas desactivarla con una condición aparte.

Nombres de transacción y etiquetas

Cada aviso de onRequestError lleva etiquetas construidas a partir del contexto que da Next: router (App o Pages), route - el patrón de la ruta, como /orders/[id], no la ruta concreta -, route_type y render_source. El patrón de ruta es lo que mantiene una ruta como una sola fila en el panel sin importar cuántos identificadores hayan pasado por ella.

Qué se elimina de un aviso

Antes de que un evento llegue a DockRay, la integración retira Authorization, Cookie, Set-Cookie, X-Api-Key y el propio token del colector del navegador de las cabeceras. La IP y el user agent del visitante solo se adjuntan con RAY_SEND_DEFAULT_PII=true; sin eso, un aviso no lleva ningún campo user.

Errores de JavaScript desde el navegador

Desactivado por defecto. Activarlo requiere dos piezas.

La ruta que los recibe - app/api/ray/browser/route.ts:

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

export const POST = createBrowserErrorRoute();
export const runtime = 'nodejs';

El colector, montado una vez en el layout raíz:

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

export default function RootLayout({ children }) {
    return (
        <html>
            <body>
                <RayBrowserReporting />
                {children}
            </body>
        </html>
    );
}

NEXT_PUBLIC_RAY_JS_ERRORS=true activa el colector - el prefijo aquí es intencionado, porque el campo solo lleva una bandera, no un secreto.

El navegador notifica a tu ruta, nunca directamente al panel: autenticarse exige la clave privada del proyecto, y una clave dentro del paquete de cliente es una clave publicada. Tu servidor reenvía cada aviso con su propia clave y rellena el sobre - id, marca de tiempo, entorno, versión -, así que el navegador nunca elige en qué entorno caen sus errores.

La ruta responde 202 a todo - un aviso válido, uno mal formado, uno rechazado por el límite - así que quien llama no aprende nada sobre las barreras. Descarta cuerpos de más de 16 KB y permite veinte avisos por dirección y minuto. El colector del navegador también se autolimita: un aviso por error distinto y vista de página, como máximo diez por vista de página por defecto, filtrando ResizeObserver loop y Script error. de origen cruzado.

Notificar a mano desde el navegador

'use client';
import { captureBrowserException } from '@dockcodes/dock-ray-next/client';

export default function GlobalError({ error }) {
    captureBrowserException(error);

    return <html><body><h1>Algo salió mal</h1></body></html>;
}

Vercel

Cuando RAY_ENVIRONMENT y RAY_RELEASE no están definidos, la integración toma VERCEL_ENV como entorno y VERCEL_GIT_COMMIT_SHA como versión, así que un despliegue preview no se notifica como producción.

Proteger la clave privada

La clave privada es un secreto del proyecto, no un identificador. Guárdala en variables de entorno, en un gestor de secretos o en la configuración del servidor: nunca en el repositorio, en los registros, en una captura de pantalla ni en código que llegue al navegador. Un proyecto puede tener varias claves, así que producción y preproducción deberían tener la suya: cada una se revoca por separado sin interrumpir a las demás. La sospecha de que una clave se ha filtrado ya es motivo suficiente para revocarla y generar otra.