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.

Pégalo en Claude Code, Cursor o cualquier asistente de programación con IA. Incluye los pasos y el código. En app.blipit.io, en Claves de API, el mismo prompt viene con tu clave ya puesta.
Vídeo: instalar Blipit en cualquier stack, desde 0:32

1Instalar

sh
npm install @blipit/nextjs

2Obté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.

Claves API en app.blipit.io: la clave pública (blipit_pk_) para el código del navegador y la clave secreta (blipit_sk_) para servidores y Odoo.
Claves API en app.blipit.io: la clave pública (blipit_pk_) para el código del navegador y la clave secreta (blipit_sk_) para servidores y Odoo.
Una nueva clave secreta se muestra una sola vez. Cópiala ahora: se guarda con hash y no se puede volver a mostrar.
Una nueva clave secreta se muestra una sola vez. Cópiala ahora: se guarda con hash y no se puede volver a mostrar.

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.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4Lado 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.

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

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_.

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

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.

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

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.

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

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.

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

9Content 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.

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

11Informes de errores: el botón Reportar un error

En cuanto el SDK arranca con tu clave pública, aparece un botón Reportar un error en la esquina inferior derecha de cada página, en el idioma del visitante. Un clic abre el formulario de reporte: una captura de la página para marcar, un selector de elementos, una grabación de pantalla opcional y un título y una descripción. Cambia la posición, el estilo, el texto, el color y el atajo de teclado en el código, como se muestra abajo, o para todos tus sitios a la vez en app.blipit.io, Ajustes del proyecto, Widget de informes de errores; las opciones del código tienen prioridad. La guía del botón de informes de errores muestra cada opción con capturas y una demo en vivo.

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",
  }}
/>
El botón Reportar un error por defecto, abajo a la derecha.
El botón Reportar un error por defecto, abajo a la derecha.
El formulario de reporte: una captura marcada, el título y lo que pasó.
El formulario de reporte: una captura marcada, el título y lo que pasó.

12Abre el formulario de reporte desde tu propio botón

Pon el botón oficial donde quieras con <BlipitReportButton />, también en server components: muestra el icono de Blipit y Reportar un error en el idioma del visitante y abre el formulario. ¿Prefieres tu propio diseño? El componente que llama a openReport debe ser un client component, así que pon "use client" al principio de su archivo. <Blipit /> ya debe estar en app/layout.tsx. Las apps de React sin Next.js importan el botón desde @blipit/nextjs/react y openReport desde @blipit/browser.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
React sin 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>;
}
El botón oficial Reportar un error en el encabezado de un sitio.
El botón oficial Reportar un error en el encabezado de un sitio.
Una app de Next.js: el botón personalizado Report Issue de la cabecera abrió el formulario de reporte de Blipit.
Una app de Next.js: el botón personalizado Report Issue de la cabecera abrió el formulario de reporte de Blipit.

13Ocultar el botón por defecto

Para quedarte solo con tu propio botón, desactiva el flotante con feedbackWidget: false en el código (feedbackWidget={false} en <Blipit />), o desactiva Mostrar el botón de informes en los ajustes del Widget de informes de errores del proyecto para ocultarlo en todos los sitios que usan la clave. openReport() y attachReport() siguen funcionando en cualquier caso.

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

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.

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

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.

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

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

16Si el botón o los eventos no aparecen

  • Abre la consola del navegador y busca las líneas que empiezan por [blipit]. Activa debug (debug: true en init, o debug en <Blipit />) para ver si el botón se mostró, se desactivó en el código o lo ocultó el ajuste del proyecto.
  • Next.js solo envía al navegador las variables cuyo nombre empieza por NEXT_PUBLIC_, así que usa NEXT_PUBLIC_BLIPIT_KEY. Vite solo envía las variables VITE_, así que usa VITE_BLIPIT_KEY. Con cualquier otro nombre la clave queda vacía en el navegador y Blipit no arranca.
  • Reinicia el servidor de desarrollo después de añadir o cambiar .env o .env.local. Solo los lee al arrancar.
  • En Vercel o en cualquier otro hosting, añade la misma variable en las variables de entorno del proyecto y vuelve a desplegar. Los valores NEXT_PUBLIC_ y VITE_ se escriben en el build, así que un despliegue en marcha nunca ve un valor añadido después.
  • Usa la clave pública (blipit_pk_). Una clave secreta (blipit_sk_) se rechaza en el navegador con un error en la consola; si alguna vez estuvo en una página, crea una nueva clave secreta.
  • En Next.js, <Blipit /> va en el app/layout.tsx raíz (o en pages/_app.tsx) para que se ejecute en todas las páginas. En otras apps, llama a init una vez en el archivo de entrada, antes de que la app se renderice.
  • Mostrar el botón de informes tiene que estar activado en app.blipit.io, Ajustes del proyecto, Widget de informes de errores, y tu código no debe pasar feedbackWidget: false. El SDK guarda los ajustes del proyecto hasta una hora, así que prueba los cambios en una ventana privada.
  • Los bloqueadores de anuncios y las extensiones de privacidad pueden bloquear in.blipit.io. Prueba en una ventana privada con las extensiones desactivadas.
  • Si tu sitio envía una Content Security Policy, permite script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: y media-src blob:. El editor del reporte se carga desde blipit.io/sdk con el primer clic, la captura se dibuja a partir de una imagen data: y las grabaciones de pantalla también se suben a in.blipit.io. Con debug activado, la consola indica cuándo la política bloqueó la captura. 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.
  • Comprueba qué versión está instalada con npm ls @blipit/browser @blipit/nextjs (o pnpm list @blipit/browser @blipit/nextjs) y compárala con el registro de cambios. pnpm 11 espera un día antes de instalar una versión nueva (minimum-release-age), así que el día del lanzamiento pnpm add instala sin avisar la versión anterior. Para obtener la nueva enseguida: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • ¿Sigue sin funcionar? Escribe a support@blipit.io con las líneas [blipit] de la consola.

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.