Next.js et React

Installation npm install @blipit/nextjs

@blipit/nextjs vous donne les erreurs navigateur, les web vitals, le session replay et le bouton Signaler un bug grâce à un seul composant dans votre layout, et les erreurs des server components, route handlers et server actions grâce à une seule ligne dans instrumentation.ts. Les applications React simples utilisent @blipit/browser.

Collez-le dans Claude Code, Cursor ou tout autre assistant de code IA. Il contient les étapes et le code. Dans app.blipit.io, sous Clés API, le même prompt est fourni avec votre clé déjà renseignée.
Vidéo : installer Blipit dans n'importe quel stack, à partir de 0:32

1Installation

sh
npm install @blipit/nextjs

2Obtenir vos clés

Connectez-vous sur app.blipit.io et ouvrez Clés API dans la barre latérale, puis votre projet. Chaque projet a deux clés. La clé publique commence par blipit_pk_ : elle va dans le code navigateur et applicatif, ne peut qu'envoyer des événements et peut être vue par n'importe qui sans risque. La clé secrète commence par blipit_sk_ : elle reste sur votre serveur ou dans Odoo, jamais dans un navigateur, car elle peut aussi lire et modifier les problèmes. La clé secrète n'est affichée qu'une fois, juste après sa création, alors copiez-la à ce moment-là ; si vous la perdez, appuyez sur Créer une nouvelle clé secrète, et l'ancienne cesse aussitôt de fonctionner. Certains SDK ont aussi besoin de l'identifiant de projet, affiché sur la même page.

Clés API dans app.blipit.io : la clé publique (blipit_pk_) pour le code navigateur et la clé secrète (blipit_sk_) pour les serveurs et Odoo.
Clés API dans app.blipit.io : la clé publique (blipit_pk_) pour le code navigateur et la clé secrète (blipit_sk_) pour les serveurs et Odoo.
Une nouvelle clé secrète n'est affichée qu'une fois. Copiez-la maintenant : elle est stockée sous forme de hash et ne peut plus être affichée.
Une nouvelle clé secrète n'est affichée qu'une fois. Copiez-la maintenant : elle est stockée sous forme de hash et ne peut plus être affichée.

3Mettez les clés dans .env.local

Créez .env.local à la racine du projet avec la clé publique pour le navigateur et, si vous utilisez la partie serveur ci-dessous, la clé secrète pour le serveur. Seuls les noms qui commencent par NEXT_PUBLIC_ atteignent le navigateur, donc ne donnez jamais ce préfixe à la clé secrète. Relancez npm run dev après avoir enregistré le fichier. En production, ajoutez les mêmes variables chez votre hébergeur (sur Vercel : Project, Settings, Environment Variables, pour Production et Preview) et redéployez : les valeurs NEXT_PUBLIC_ sont écrites dans le build, donc un déploiement fait avant leur ajout a une clé vide.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4Côté navigateur

Ajoutez le composant une seule fois dans le layout racine. Il lit la clé publique depuis NEXT_PUBLIC_BLIPIT_KEY. Si la variable est vide, il ne démarre rien et l'indique dans la console du navigateur.

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

5Côté serveur

Next.js 15 et suivants appellent onRequestError pour les erreurs des composants serveur, route handlers et server actions. Une ligne dans instrumentation.ts le relie à Blipit. Depuis @blipit/nextjs 0.2.1, la même ligne fonctionne aussi dans les apps qui ont un middleware.ts et dans les routes Edge (runtime = "edge") : l'app se compile, et les erreurs du middleware et d'Edge sont signalées elles aussi. Next.js 14 n'a pas onRequestError : enveloppez alors chaque route handler et server action dans withBlipit, comme dans le second exemple ; il signale l'erreur puis la relance, et ignore les redirections et notFound(). Définissez BLIPIT_SECRET_KEY dans l'environnement serveur, jamais en 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());
});

6Dépendances et santé des serveurs

À partir de @blipit/nextjs 0.3, exportez aussi register pour que Blipit démarre avec le serveur. Il enregistre alors les appels à la base de données et aux services externes sur la page Dépendances, et le CPU, la mémoire et la boucle d'événements du serveur sur Santé des serveurs. Il ne fait rien dans le runtime Edge. Sur Vercel, register peut ne pas voir la requête entrante : depuis @blipit/nextjs 0.4, enveloppez les route handlers et server actions dans withBlipit et chacun devient une requête sur la page Pulse avec ses appels à la base de données et aux services externes, envoyée après la réponse sans la retarder.

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

7Erreurs interceptées par error.tsx

Les erreurs interceptées par une boundary error.tsx ou global-error.tsx n'atteignent jamais le gestionnaire d'erreurs du navigateur, donc signalez-les depuis la boundary. Ces deux fichiers sont des 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>
  );
}

8Gardez les clés hors de git

Gardez les clés dans des variables d'environnement ou dans les réglages de secrets de votre hébergeur, jamais dans du code que vous committez, et ajoutez vos fichiers .env à .gitignore. Une clé publique dans une page web est normale. Si une clé secrète se retrouve un jour dans git, sur une page publique, dans une capture d'écran ou dans un chat, ouvrez Clés API, appuyez sur Créer une nouvelle clé secrète, et collez la nouvelle clé partout où l'ancienne était utilisée : l'ancienne clé cesse immédiatement de fonctionner.

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

9Content Security Policy

Si votre site envoie une Content Security Policy, autorisez script-src https://blipit.io (la balise script, ainsi que l'éditeur du signalement et le module de replay, chargés depuis blipit.io/sdk/<version>/ à la première utilisation), connect-src https://in.blipit.io (les événements, les captures et les enregistrements d'écran partent tous vers in.blipit.io), img-src data: (la capture est dessinée à partir d'une image de la page) et media-src blob: (les enregistrements sont lus dans le signalement). La capture recharge les images et les polices de la page : leurs hôtes doivent donc aussi figurer dans connect-src, sinon elles restent vides. Aucun changement de style-src n'est nécessaire. Avec la balise script, appelez Blipit.init depuis votre propre fichier .js ou donnez un nonce au script en ligne, car une politique stricte bloque les scripts en ligne. Pour que les enregistrements d'écran aient du son, l'en-tête Permissions-Policy de votre site doit autoriser microphone=(self), et display-capture=(self) pour l'enregistrement d'écran ; avec microphone=() les enregistrements fonctionnent sans son.

10Source maps (facultatif)

Pour que les stack traces affichent votre source au lieu du bundle minifié, envoyez les maps de chaque release depuis votre étape de build.

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

11Rapports de bugs : le bouton Signaler un bug

Dès que le SDK démarre avec votre clé publique, un bouton Signaler un bug apparaît dans le coin inférieur droit de chaque page, dans la langue du visiteur. Un clic ouvre le formulaire de signalement : une capture de la page à annoter, un sélecteur d'élément, un enregistrement d'écran facultatif, ainsi qu'un titre et une description. Modifiez la position, le style, le texte, la couleur et le raccourci clavier dans le code, comme ci-dessous, ou pour tous vos sites à la fois dans app.blipit.io, Paramètres du projet, Widget de rapport de bug ; les options du code l'emportent. Le guide du bouton de rapport de bug présente chaque option avec des captures d'écran et une démo en direct.

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",
  }}
/>
Le bouton Signaler un bug par défaut, en bas à droite.
Le bouton Signaler un bug par défaut, en bas à droite.
Le formulaire : une capture d'écran annotée, le titre et ce qui s'est passé.
Le formulaire : une capture d'écran annotée, le titre et ce qui s'est passé.

12Ouvrir le formulaire depuis votre propre bouton

Placez le bouton officiel n'importe où avec <BlipitReportButton />, y compris dans les server components : il affiche l'icône Blipit et Signaler un bug dans la langue du visiteur et ouvre le formulaire. Vous préférez votre propre design ? Le composant qui appelle openReport doit être un client component, donc mettez "use client" en haut de son fichier. <Blipit /> doit déjà être dans app/layout.tsx. Les apps React classiques importent le bouton depuis @blipit/nextjs/react et openReport depuis @blipit/browser.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
React sans 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>;
}
Le bouton officiel Signaler un bug dans l'en-tête d'un site.
Le bouton officiel Signaler un bug dans l'en-tête d'un site.
Une application Next.js : le bouton Report Issue personnalisé dans l'en-tête a ouvert le formulaire Blipit.
Une application Next.js : le bouton Report Issue personnalisé dans l'en-tête a ouvert le formulaire Blipit.

13Masquer le bouton par défaut

Pour ne garder que votre propre bouton, désactivez le bouton flottant avec feedbackWidget: false dans le code (feedbackWidget={false} sur <Blipit />), ou désactivez Afficher le bouton de rapport de bug dans les réglages Widget de rapport de bug du projet pour le masquer sur tous les sites qui utilisent la clé. openReport() et attachReport() continuent de fonctionner dans les deux cas.

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

14Pré-remplir le formulaire et ajouter du contexte

Appelez setUser après la connexion : le nom et l'e-mail de la personne qui signale sont pré-remplis, et elle reçoit un e-mail quand vous répondez ou changez le statut. setReportMetadata ajoute vos propres champs, comme le forfait ou la taille du panier, à chaque signalement ; il s'exécute à l'envoi du signalement, donc les valeurs sont à jour.

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

15Vérifier que ça fonctionne

Rechargez l'application. Le bouton Signaler un bug apparaît dans le coin inférieur droit, et en moins d'une minute la page vue s'affiche sous Web vitals dans app.blipit.io. Ajoutez ensuite un bouton qui appelle captureMessage, ou un bouton qui lève une erreur, et cliquez dessus : l'événement apparaît sous Problèmes en quelques secondes.

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 le bouton ou les événements n'apparaissent pas

  • Ouvrez la console du navigateur et cherchez les lignes qui commencent par [blipit]. Activez debug (debug: true dans init, ou debug sur <Blipit />) pour savoir si le bouton a été affiché, désactivé dans le code ou masqué par le réglage du projet.
  • Next.js n'envoie au navigateur que les variables dont le nom commence par NEXT_PUBLIC_, donc utilisez NEXT_PUBLIC_BLIPIT_KEY. Vite n'envoie que les variables VITE_, donc utilisez VITE_BLIPIT_KEY. Avec tout autre nom, la clé est vide dans le navigateur et Blipit ne démarre pas.
  • Redémarrez le serveur de développement après avoir ajouté ou modifié .env ou .env.local. Il ne les lit qu'au démarrage.
  • Sur Vercel ou tout autre hébergeur, ajoutez la même variable dans les variables d'environnement du projet et redéployez. Les valeurs NEXT_PUBLIC_ et VITE_ sont écrites dans le build, donc un déploiement en cours ne voit jamais une valeur ajoutée plus tard.
  • Utilisez la clé publique (blipit_pk_). Une clé secrète (blipit_sk_) est refusée dans le navigateur avec une erreur dans la console ; si l'une d'elles s'est déjà retrouvée sur une page, créez une nouvelle clé secrète.
  • Dans Next.js, <Blipit /> se place dans le app/layout.tsx racine (ou pages/_app.tsx) pour s'exécuter sur chaque page. Dans les autres applications, appelez init une seule fois dans le fichier d'entrée, avant le rendu de l'application.
  • Afficher le bouton de rapport de bug doit être activé dans app.blipit.io, Paramètres du projet, Widget de rapport de bug, et votre code ne doit pas passer feedbackWidget: false. Le SDK conserve les paramètres du projet jusqu'à une heure, donc testez une modification dans une fenêtre privée.
  • Les bloqueurs de publicité et les extensions de confidentialité peuvent bloquer in.blipit.io. Essayez une fenêtre privée avec les extensions désactivées.
  • Si votre site envoie une Content Security Policy, autorisez script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: et media-src blob:. L'éditeur du signalement se charge depuis blipit.io/sdk au premier clic, la capture est dessinée à partir d'une image data: et les enregistrements d'écran sont eux aussi envoyés à in.blipit.io. Avec debug, la console indique quand la politique a bloqué la capture. Pour que les enregistrements d'écran aient du son, l'en-tête Permissions-Policy de votre site doit autoriser microphone=(self), et display-capture=(self) pour l'enregistrement d'écran ; avec microphone=() les enregistrements fonctionnent sans son.
  • Vérifiez la version installée avec npm ls @blipit/browser @blipit/nextjs (ou pnpm list @blipit/browser @blipit/nextjs) et comparez-la au journal des modifications. pnpm 11 attend un jour avant d'installer une nouvelle version (minimum-release-age) : le jour de la sortie, pnpm add installe donc sans prévenir la version précédente. Pour obtenir la nouvelle tout de suite : pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Toujours bloqué ? Écrivez à support@blipit.io en joignant les lignes [blipit] de la console.

Bon à savoir

  • React simple sans Next.js : npm install @blipit/browser et appelez Blipit.init avant le rendu ; voir Tout site web.
  • Environment et release prennent par défaut VERCEL_ENV et VERCEL_GIT_COMMIT_SHA côté serveur si vous les omettez.
  • Garder Blipit à jour : le guide Garder Blipit à jour (docs.blipit.io/updates) explique la bannière de mise à jour, les e-mails pour les versions importantes, l'avis dans votre console de développement et la commande de mise à jour pour cette plateforme.
  • Un projet par application et par plateforme : chaque projet choisit sa plateforme à sa création (Android, iOS, React Native, Flutter, Web, Backend ou Odoo), et Blipit refuse avec une erreur claire les données de toute autre plateforme. Une app iOS et une app Android ont donc besoin de deux projets avec deux clés. Les releases, les versions, les taux de plantage et les builds des stores diffèrent selon la plateforme, et les mélanger dans un projet les rend tous faux. Un projet Web accepte aussi la partie serveur de la même app web (le serveur Next.js ou Node), et un projet React Native ou Flutter accepte aussi ses propres rapports de plantage natifs Android et iOS.

Bloqué ? Écrivez à support@blipit.io. Les clés et l'identifiant de chaque projet sont sous Clés API dans app.blipit.io.