Instalar por plataforma
Next.js y React
Instalar npm install @blipit/nextjs
@blipit/nextjs te da los errores del navegador, las web vitals, el session replay y el botón Reportar un error con un solo componente en tu layout, y los errores de server components, route handlers y server actions con una sola línea en instrumentation.ts. Las apps de React sin framework usan @blipit/browser.
1Instalar
npm install @blipit/nextjs2Obtén tus claves
Inicia sesión en app.blipit.io y abre Claves API en la barra lateral y luego tu proyecto. Cada proyecto tiene dos claves. La clave pública empieza por blipit_pk_: va en el código del navegador y de las apps, solo puede enviar eventos y cualquiera puede verla sin riesgo. La clave secreta empieza por blipit_sk_: se queda en tu servidor o en Odoo, nunca en un navegador, porque también puede leer y cambiar incidencias. La clave secreta solo se muestra una vez, justo al crearla, así que cópiala entonces; si la pierdes, pulsa Crear una nueva clave secreta y la anterior deja de funcionar al instante. Algunos SDKs también necesitan el id del proyecto, que aparece en la misma página.
3Pon las claves en .env.local
Crea .env.local en la raíz del proyecto con la clave pública para el navegador y, si usas el lado del servidor descrito abajo, la clave secreta para el servidor. Solo los nombres que empiezan por NEXT_PUBLIC_ llegan al navegador, así que nunca le pongas ese prefijo a la clave secreta. Reinicia npm run dev después de guardar el archivo. Para producción, añade las mismas variables en tu hosting (en Vercel: Project, Settings, Environment Variables, para Production y Preview) y vuelve a desplegar: los valores NEXT_PUBLIC_ se escriben en el build, así que un despliegue hecho antes de añadirlos tiene la clave vacía.
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key4Lado del navegador
Añade el componente una sola vez en el layout raíz. Lee la clave pública de NEXT_PUBLIC_BLIPIT_KEY. Si la variable está vacía, no inicia nada y lo indica en la consola del navegador.
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>
);
}5Lado del servidor
Next.js 15 y posteriores llaman a onRequestError para los errores en componentes de servidor, route handlers y server actions. Una línea en instrumentation.ts lo conecta con Blipit. Desde @blipit/nextjs 0.2.1, la misma línea también funciona en apps con un middleware.ts y en rutas Edge (runtime = "edge"): la app compila y los errores del middleware y de Edge también se reportan. Next.js 14 no tiene onRequestError, así que envuelve cada route handler y server action con withBlipit, como en el segundo ejemplo: reporta el error y lo vuelve a lanzar, y omite las redirecciones y notFound(). Define BLIPIT_SECRET_KEY en el entorno del servidor, nunca como NEXT_PUBLIC_.
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";import { withBlipit } from "@blipit/nextjs/server";
export const GET = withBlipit(async (request: Request) => {
return Response.json(await loadOrders());
});6Dependencias y salud del servidor
Desde @blipit/nextjs 0.3, exporta también register para que Blipit arranque con el servidor. Así registra las llamadas a la base de datos y a servicios externos en la página Dependencias, y la CPU, memoria y bucle de eventos del servidor en Salud del servidor. No hace nada en el runtime Edge. En Vercel, register puede no ver la petición entrante: desde @blipit/nextjs 0.4, envuelve los route handlers y server actions en withBlipit y cada uno se convierte en una petición en la página Pulse con sus llamadas a la base de datos y a servicios externos, enviada después de la respuesta sin retrasarla.
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";import { withBlipit } from "@blipit/nextjs/server";
export const GET = withBlipit(async (request: Request) => Response.json(await loadOrders()));7Errores capturados por error.tsx
Los errores que captura un boundary error.tsx o global-error.tsx nunca llegan al manejador de errores del navegador, así que repórtalos desde el boundary. Ambos archivos son client components.
"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>
);
}"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>
);
}8Mantén las claves fuera de git
Guarda las claves en variables de entorno o en los ajustes de secretos de tu hosting, nunca en código que subas con commit, y añade tus archivos .env a .gitignore. Una clave pública en una página web es normal. Si alguna vez una clave secreta acaba en git, en una página pública, en una captura o en un chat, abre Claves API, pulsa Crear una nueva clave secreta y pega la nueva clave donde se usaba la anterior: la clave anterior deja de funcionar al instante.
.env
.env.local
.env.*.local9Content Security Policy
Si tu sitio envía una Content Security Policy, permite script-src https://blipit.io (la etiqueta script, y el editor del reporte y el complemento de replay, que se cargan desde blipit.io/sdk/<version>/ la primera vez que se usan), connect-src https://in.blipit.io (los eventos, las capturas y las grabaciones de pantalla van todos a in.blipit.io), img-src data: (la captura se dibuja a partir de una imagen de la página) y media-src blob: (las grabaciones se reproducen en el reporte). La captura vuelve a cargar las imágenes y fuentes de la página, así que sus hosts también deben estar en connect-src; si no, quedan en blanco. No hace falta cambiar style-src. Con la etiqueta script, llama a Blipit.init desde tu propio archivo .js o da un nonce al script en línea, porque una política estricta bloquea los scripts en línea. Para que las grabaciones de pantalla tengan voz, la cabecera Permissions-Policy de tu sitio debe permitir microphone=(self), y display-capture=(self) para grabar la pantalla; con microphone=() las grabaciones funcionan sin sonido.
10Source maps (opcional)
Para que los stack traces muestren tu código fuente en lugar del bundle minificado, sube los maps de cada release desde tu paso de build.
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"14Rellena el formulario de reporte y añade contexto
Llama a setUser tras el inicio de sesión: el nombre y el correo de quien reporta se rellenan solos, y recibe un correo cuando respondes o cambias el estado. setReportMetadata añade tus propios campos, como el plan o el tamaño del carrito, a cada reporte; se ejecuta cuando se envía un reporte, así que los valores están al día.
"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;
}15Comprueba que funciona
Recarga la app. El botón Reportar un error aparece en la esquina inferior derecha y, en menos de un minuto, la vista de página aparece en Web vitals en app.blipit.io. Después añade un botón que llame a captureMessage, o uno que lance un error, y haz clic: el evento aparece en Incidencias en unos segundos.
"use client";
import { captureMessage } from "@blipit/nextjs";
export function TestBlipit() {
return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}Conviene saber
- React sin Next.js: npm install @blipit/browser y llama a Blipit.init antes de renderizar; consulta Cualquier sitio web.
- En el servidor, environment y release toman por defecto VERCEL_ENV y VERCEL_GIT_COMMIT_SHA cuando los omites.
- Mantener Blipit actualizado: la guía Mantener Blipit actualizado (docs.blipit.io/updates) explica el banner de actualización, los correos para versiones importantes, el aviso en tu consola de desarrollo y el comando de actualización para esta plataforma.
- Un proyecto por app y plataforma: cada proyecto elige su plataforma al crearse (Android, iOS, React Native, Flutter, Web, Backend u Odoo) y Blipit rechaza con un error claro los datos de cualquier otra plataforma, así que una app de iOS y una de Android necesitan dos proyectos con dos claves. Las versiones, las compilaciones, las tasas de fallos y las builds de tienda son distintas en cada plataforma, y mezclarlas en un proyecto hace que todas sean incorrectas. Un proyecto Web también acepta la parte de servidor de la misma app web (el servidor de Next.js o Node), y un proyecto de React Native o Flutter también acepta sus propios informes de fallos nativos de Android e iOS.
¿Atascado? Escribe a support@blipit.io. Las claves y el id de cada proyecto están en Claves API en app.blipit.io.





