Next.js e React

Installazione npm install @blipit/nextjs

@blipit/nextjs ti dà errori del browser, web vitals, session replay e il pulsante Segnala un bug con un solo componente nel layout, e gli errori di server component, route handler e server action con una sola riga in instrumentation.ts. Le app React semplici usano @blipit/browser.

Incollalo in Claude Code, Cursor o in qualsiasi assistente di programmazione IA. Contiene i passaggi e il codice. In app.blipit.io, in Chiavi API, lo stesso prompt ha già la tua chiave inserita.
Video: installare Blipit in qualsiasi stack, da 0:32

1Installazione

sh
npm install @blipit/nextjs

2Ottieni le chiavi

Accedi su app.blipit.io e apri Chiavi API nella barra laterale, poi il tuo progetto. Ogni progetto ha due chiavi. La chiave pubblica inizia con blipit_pk_: va nel codice del browser e delle app, può solo inviare eventi e chiunque può vederla senza rischi. La chiave segreta inizia con blipit_sk_: resta sul tuo server o in Odoo, mai in un browser, perché può anche leggere e modificare le issue. La chiave segreta viene mostrata una sola volta, subito dopo la creazione, quindi copiala in quel momento; se la perdi, premi Crea una nuova chiave segreta e quella vecchia smette subito di funzionare. Alcuni SDK richiedono anche l'id del progetto, mostrato nella stessa pagina.

Chiavi API su app.blipit.io: la chiave pubblica (blipit_pk_) per il codice del browser e la chiave segreta (blipit_sk_) per i server e Odoo.
Chiavi API su app.blipit.io: la chiave pubblica (blipit_pk_) per il codice del browser e la chiave segreta (blipit_sk_) per i server e Odoo.
Una nuova chiave segreta viene mostrata una sola volta. Copiala subito: viene salvata come hash e non può essere mostrata di nuovo.
Una nuova chiave segreta viene mostrata una sola volta. Copiala subito: viene salvata come hash e non può essere mostrata di nuovo.

3Metti le chiavi in .env.local

Crea .env.local nella root del progetto con la chiave pubblica per il browser e, se usi la parte server qui sotto, la chiave segreta per il server. Solo i nomi che iniziano con NEXT_PUBLIC_ arrivano al browser, quindi non dare mai quel prefisso alla chiave segreta. Riavvia npm run dev dopo aver salvato il file. Per la produzione, aggiungi le stesse variabili nel tuo host (su Vercel: Project, Settings, Environment Variables, per Production e Preview) e fai di nuovo il deploy: i valori NEXT_PUBLIC_ vengono scritti nella build, quindi un deploy fatto prima di aggiungerli ha una chiave vuota.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4Lato browser

Aggiungi il componente una sola volta nel layout principale. Legge la chiave pubblica da NEXT_PUBLIC_BLIPIT_KEY. Se la variabile è vuota, non avvia nulla e lo segnala nella console del browser.

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

5Lato server

Next.js 15 e successivi chiamano onRequestError per gli errori in server component, route handler e server action. Una riga in instrumentation.ts lo collega a Blipit. Da @blipit/nextjs 0.2.1 la stessa riga funziona anche nelle app con un middleware.ts e nelle route Edge (runtime = "edge"): l'app si compila e vengono segnalati anche gli errori del middleware e di Edge. Next.js 14 non ha onRequestError, quindi avvolgi ogni route handler e server action in withBlipit, come nel secondo esempio: segnala l'errore e lo rilancia, e salta i redirect e notFound(). Imposta BLIPIT_SECRET_KEY nell'ambiente del server, mai come 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());
});

6Dipendenze e stato dei server

Da @blipit/nextjs 0.3 esporta anche register, così Blipit parte all'avvio del server. Registra quindi le chiamate al database e ai servizi esterni nella pagina Dipendenze, e CPU, memoria ed event loop del server in Stato dei server. Nel runtime Edge non fa nulla. Su Vercel, register potrebbe non vedere la richiesta in arrivo: da @blipit/nextjs 0.4, avvolgi route handler e server action in withBlipit e ognuno diventa una richiesta nella pagina Pulse con le sue chiamate al database e ai servizi esterni, inviata dopo la risposta senza rallentarla.

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

7Errori catturati da error.tsx

Gli errori catturati da un boundary error.tsx o global-error.tsx non arrivano mai al gestore degli errori del browser, quindi segnalali dal boundary. Entrambi i file sono client component.

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

8Tieni le chiavi fuori da git

Tieni le chiavi in variabili d'ambiente o nelle impostazioni dei secret del tuo host, mai nel codice che fai commit, e aggiungi i tuoi file .env a .gitignore. Una chiave pubblica in una pagina web è normale. Se una chiave segreta finisce in git, in una pagina pubblica, in uno screenshot o in una chat, apri Chiavi API, premi Crea una nuova chiave segreta e incolla la nuova chiave ovunque usavi quella vecchia: la vecchia chiave smette di funzionare subito.

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

9Content Security Policy

Se il tuo sito invia una Content Security Policy, consenti script-src https://blipit.io (il tag script, l'editor della segnalazione e il modulo di replay, che si caricano da blipit.io/sdk/<version>/ al primo utilizzo), connect-src https://in.blipit.io (eventi, screenshot e registrazioni dello schermo vanno tutti a in.blipit.io), img-src data: (lo screenshot viene disegnato da un'immagine della pagina) e media-src blob: (le registrazioni vengono riprodotte nella segnalazione). Lo screenshot ricarica le immagini e i font della pagina, quindi anche i loro host vanno in connect-src, altrimenti restano vuoti. Non serve modificare style-src. Con il tag script, chiama Blipit.init da un tuo file .js o assegna un nonce allo script inline, perché una policy rigorosa blocca gli script inline. Perché le registrazioni dello schermo abbiano l'audio, l'header Permissions-Policy del sito deve consentire microphone=(self), e display-capture=(self) per la registrazione dello schermo; con microphone=() le registrazioni funzionano senza audio.

10Source map (facoltativo)

Perché gli stack trace mostrino il tuo sorgente invece del bundle minificato, carica le map di ogni release dal tuo passaggio di build.

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

11Segnalazioni di bug: il pulsante Segnala un bug

Appena l'SDK si avvia con la tua chiave pubblica, compare un pulsante Segnala un bug nell'angolo in basso a destra di ogni pagina, nella lingua del visitatore. Un clic apre il modulo di segnalazione: uno screenshot della pagina da annotare, un selettore di elementi, una registrazione dello schermo facoltativa, un titolo e una descrizione. Cambia posizione, stile, testo, colore e scorciatoia da tastiera nel codice, come qui sotto, oppure per tutti i siti insieme su app.blipit.io, Impostazioni del progetto, Widget di segnalazione bug; le opzioni nel codice hanno la precedenza. La guida al pulsante di segnalazione bug mostra ogni opzione con screenshot e una demo dal 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",
  }}
/>
Il pulsante predefinito Segnala un bug, in basso a destra.
Il pulsante predefinito Segnala un bug, in basso a destra.
Il modulo di segnalazione: uno screenshot annotato, il titolo e cosa è successo.
Il modulo di segnalazione: uno screenshot annotato, il titolo e cosa è successo.

12Aprire il modulo di segnalazione dal tuo pulsante

Metti il pulsante ufficiale ovunque con <BlipitReportButton />, anche nei server component: mostra l'icona di Blipit e Segnala un bug nella lingua del visitatore e apre il modulo. Preferisci un design tuo? Il componente che chiama openReport deve essere un client component, quindi metti "use client" all'inizio del suo file. <Blipit /> deve essere già in app/layout.tsx. Le app React senza Next.js importano il pulsante da @blipit/nextjs/react e openReport da @blipit/browser.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
React senza 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>;
}
Il pulsante ufficiale Segnala un bug nell'intestazione di un sito.
Il pulsante ufficiale Segnala un bug nell'intestazione di un sito.
Un'app Next.js: il pulsante personalizzato Report Issue nell'header ha aperto il modulo di segnalazione Blipit.
Un'app Next.js: il pulsante personalizzato Report Issue nell'header ha aperto il modulo di segnalazione Blipit.

13Nascondere il pulsante predefinito

Per tenere solo il tuo pulsante, disattiva quello flottante con feedbackWidget: false nel codice (feedbackWidget={false} su <Blipit />), oppure disattiva Mostra il pulsante di segnalazione nelle impostazioni del Widget di segnalazione bug del progetto per nasconderlo su ogni sito che usa la chiave. openReport() e attachReport() continuano a funzionare in entrambi i casi.

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

14Precompilare il modulo di segnalazione e aggiungere contesto

Chiama setUser dopo l'accesso: nome ed email di chi segnala vengono compilati, e riceve un'email quando rispondi o cambi lo stato. setReportMetadata aggiunge i tuoi campi, come il piano o la dimensione del carrello, a ogni segnalazione; viene eseguita quando la segnalazione viene inviata, quindi i valori sono aggiornati.

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

15Verifica che funzioni

Ricarica l'app. Il pulsante Segnala un bug compare nell'angolo in basso a destra, e entro un minuto la visualizzazione di pagina compare in Web vitals su app.blipit.io. Poi aggiungi un pulsante che chiama captureMessage, o uno che lancia un errore, e cliccalo: l'evento compare in Issue entro pochi secondi.

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

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

16Se il pulsante o gli eventi non compaiono

  • Apri la console del browser e cerca le righe che iniziano con [blipit]. Attiva debug (debug: true in init, oppure debug su <Blipit />) per vedere se il pulsante è stato mostrato, disattivato nel codice o nascosto dall'impostazione del progetto.
  • Next.js invia al browser solo le variabili il cui nome inizia con NEXT_PUBLIC_, quindi usa NEXT_PUBLIC_BLIPIT_KEY. Vite invia solo le variabili VITE_, quindi usa VITE_BLIPIT_KEY. Con qualsiasi altro nome la chiave è vuota nel browser e Blipit non si avvia.
  • Riavvia il dev server dopo aver aggiunto o modificato .env o .env.local. Li legge solo all'avvio.
  • Su Vercel o qualsiasi altro host, aggiungi la stessa variabile nelle variabili d'ambiente del progetto e fai di nuovo il deploy. I valori NEXT_PUBLIC_ e VITE_ vengono scritti nella build, quindi un deploy già in esecuzione non vede mai un valore aggiunto dopo.
  • Usa la chiave pubblica (blipit_pk_). Una chiave segreta (blipit_sk_) viene rifiutata nel browser con un errore in console; se una è mai finita in una pagina, crea una nuova chiave segreta.
  • In Next.js, <Blipit /> va nel file principale app/layout.tsx (o pages/_app.tsx), così viene eseguito in ogni pagina. Nelle altre app, chiama init una sola volta nel file di ingresso, prima che l'app venga renderizzata.
  • Mostra il pulsante di segnalazione deve essere attivo su app.blipit.io, Impostazioni del progetto, Widget di segnalazione bug, e il tuo codice non deve passare feedbackWidget: false. L'SDK conserva le impostazioni del progetto fino a un'ora, quindi prova una modifica in una finestra privata.
  • Gli ad blocker e le estensioni per la privacy possono bloccare in.blipit.io. Prova una finestra privata con le estensioni disattivate.
  • Se il tuo sito invia una Content Security Policy, consenti script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: e media-src blob:. L'editor della segnalazione si carica da blipit.io/sdk al primo clic, lo screenshot viene disegnato da un'immagine data: e anche le registrazioni dello schermo vengono caricate su in.blipit.io. Con debug attivo, la console indica quando la policy ha bloccato lo screenshot. Perché le registrazioni dello schermo abbiano l'audio, l'header Permissions-Policy del sito deve consentire microphone=(self), e display-capture=(self) per la registrazione dello schermo; con microphone=() le registrazioni funzionano senza audio.
  • Controlla quale versione è installata con npm ls @blipit/browser @blipit/nextjs (o pnpm list @blipit/browser @blipit/nextjs) e confrontala con il changelog. pnpm 11 aspetta un giorno prima di installare una nuova versione (minimum-release-age), quindi il giorno del rilascio pnpm add installa in silenzio la versione precedente. Per avere subito quella nuova: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Ancora bloccato? Scrivi a support@blipit.io allegando le righe [blipit] della console.

Buono a sapersi

  • React semplice senza Next.js: npm install @blipit/browser e chiama Blipit.init prima del rendering; vedi Qualsiasi sito web.
  • Ambiente e release sul server usano per impostazione predefinita VERCEL_ENV e VERCEL_GIT_COMMIT_SHA quando li ometti.
  • Tenere Blipit aggiornato: la guida Tenere Blipit aggiornato (docs.blipit.io/updates) spiega il banner di aggiornamento, le email per le versioni importanti, l'avviso nella console di sviluppo e il comando di aggiornamento per questa piattaforma.
  • Un progetto per app e piattaforma: ogni progetto sceglie la sua piattaforma quando viene creato (Android, iOS, React Native, Flutter, Web, Backend o Odoo) e Blipit rifiuta con un errore chiaro i dati di qualsiasi altra piattaforma, quindi un'app iOS e un'app Android hanno bisogno di due progetti con due chiavi. Release, versioni, tassi di crash e build per gli store sono diversi per ogni piattaforma, e mescolarli in un progetto li rende tutti sbagliati. Un progetto Web accetta anche la parte server della stessa app web (il server Next.js o Node), e un progetto React Native o Flutter accetta anche i propri crash nativi Android e iOS.

Bloccato? Scrivi a support@blipit.io. Le chiavi e l'id di ogni progetto sono sotto Chiavi API in app.blipit.io.