Next.js e React

Instalar npm install @blipit/nextjs

O @blipit/nextjs oferece erros do navegador, web vitals, session replay e o botão Reportar erro a partir de um único componente no seu layout, além de erros de server components, route handlers e server actions com uma linha em instrumentation.ts. Apps React puros usam @blipit/browser.

Cole-o no Claude Code, no Cursor ou em qualquer assistente de programação com IA. Inclui os passos e o código. Em app.blipit.io, em Chaves de API, o mesmo prompt já vem com a sua chave preenchida.
Vídeo: instalar o Blipit em qualquer stack, a partir de 0:32

1Instalar

sh
npm install @blipit/nextjs

2Obtenha suas chaves

Entre no app.blipit.io e abra Chaves de API na barra lateral, depois o seu projeto. Cada projeto tem duas chaves. A chave pública começa com blipit_pk_: ela vai no código do navegador e do app, só pode enviar eventos e é segura para qualquer pessoa ver. A chave secreta começa com blipit_sk_: ela fica no seu servidor ou no Odoo, nunca em um navegador, porque também pode ler e alterar problemas. A chave secreta é exibida uma única vez, logo depois de criada, então copie-a nesse momento; se você a perder, clique em Criar uma nova chave secreta, e a antiga para de funcionar na hora. Alguns SDKs também precisam do id do projeto, exibido na mesma página.

Chaves de API no app.blipit.io: a chave pública (blipit_pk_) para código de navegador e a chave secreta (blipit_sk_) para servidores e o Odoo.
Chaves de API no app.blipit.io: a chave pública (blipit_pk_) para código de navegador e a chave secreta (blipit_sk_) para servidores e o Odoo.
Uma nova chave secreta é exibida uma única vez. Copie-a agora: ela é armazenada com hash e não pode ser exibida novamente.
Uma nova chave secreta é exibida uma única vez. Copie-a agora: ela é armazenada com hash e não pode ser exibida novamente.

3Coloque as chaves em .env.local

Crie .env.local na raiz do projeto com a chave pública para o navegador e, se você usar o lado do servidor abaixo, a chave secreta para o servidor. Só os nomes que começam com NEXT_PUBLIC_ chegam ao navegador, então nunca dê esse prefixo à chave secreta. Reinicie o npm run dev depois de salvar o arquivo. Para produção, adicione as mesmas variáveis no seu host (na Vercel: Project, Settings, Environment Variables, para Production e Preview) e faça o deploy novamente: os valores NEXT_PUBLIC_ são gravados no build, então um deploy feito antes de você adicioná-los tem a chave vazia.

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4Lado do navegador

Adicione o componente uma única vez no layout raiz. Ele lê a chave pública de NEXT_PUBLIC_BLIPIT_KEY. Se a variável estiver vazia, ele não inicia nada e avisa no console do 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 do servidor

O Next.js 15 e posteriores chamam onRequestError para erros em server components, route handlers e server actions. Uma linha em instrumentation.ts o conecta ao Blipit. A partir do @blipit/nextjs 0.2.1, a mesma linha também funciona em apps com um middleware.ts e em rotas Edge (runtime = "edge"): o app compila, e os erros do middleware e do Edge também são reportados. O Next.js 14 não tem onRequestError, então envolva cada route handler e server action com withBlipit, como no segundo exemplo: ele reporta o erro e o lança de novo, e ignora redirecionamentos e notFound(). Defina BLIPIT_SECRET_KEY no ambiente do 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());
});

6Dependências e saúde do servidor

A partir do @blipit/nextjs 0.3, exporte também register para que o Blipit arranque com o servidor. Assim regista as chamadas à base de dados e a serviços externos na página Dependências, e o CPU, memória e event loop do servidor em Saúde do servidor. Não faz nada no runtime Edge. Na Vercel, register pode não ver o pedido recebido: a partir de @blipit/nextjs 0.4, envolva os route handlers e server actions em withBlipit e cada um passa a ser um pedido na página Pulse com as suas chamadas à base de dados e a serviços externos, enviado depois da resposta sem a atrasar.

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

7Erros capturados por error.tsx

Erros que um boundary error.tsx ou global-error.tsx captura nunca chegam ao handler de erros do navegador, então reporte-os a partir do boundary. Os dois arquivos são 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>
  );
}

8Mantenha as chaves fora do git

Mantenha as chaves em variáveis de ambiente ou nas configurações de segredos do seu host, nunca em código que você faz commit, e adicione seus arquivos .env ao .gitignore. Uma chave pública em uma página web é normal. Se uma chave secreta for parar no git, em uma página pública, em uma captura de tela ou em um chat, abra Chaves de API, clique em Criar uma nova chave secreta e cole a nova chave onde a antiga era usada: a chave antiga para de funcionar na hora.

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

9Content Security Policy

Se o seu site envia uma Content Security Policy, permita script-src https://blipit.io (a tag script, e o editor do relato e o complemento de replay, que carregam de blipit.io/sdk/<version>/ no primeiro uso), connect-src https://in.blipit.io (eventos, capturas e gravações de tela vão todos para in.blipit.io), img-src data: (a captura é desenhada a partir de uma imagem da página) e media-src blob: (as gravações são reproduzidas no relato). A captura recarrega as imagens e fontes da página, então os hosts delas também precisam estar em connect-src, senão ficam em branco. Não é preciso mudar style-src. Com a tag script, chame Blipit.init a partir do seu próprio arquivo .js ou dê um nonce ao script inline, porque uma política rígida bloqueia scripts inline. Para que as gravações de tela tenham voz, o cabeçalho Permissions-Policy do site precisa permitir microphone=(self), e display-capture=(self) para a gravação de tela; com microphone=() as gravações funcionam sem som.

10Source maps (opcional)

Para que os stack traces mostrem seu código-fonte em vez do bundle minificado, envie os maps de cada release a partir da sua etapa de build.

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

11Relatórios de bugs: o botão Reportar erro

Assim que o SDK inicia com a sua chave pública, um botão Reportar erro aparece no canto inferior direito de cada página, no idioma do visitante. Um clique abre o formulário de relato: uma captura de tela da página para marcar, um seletor de elementos, uma gravação de tela opcional, e um título e uma descrição. Altere a posição, o estilo, o texto, a cor e o atalho de teclado no código, como abaixo, ou para todos os sites de uma vez no app.blipit.io, em Configurações do projeto, Widget de relatório de bugs; as opções no código prevalecem. O guia do botão de relatório de bug mostra cada opção com capturas de tela e uma demonstração ao 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",
  }}
/>
O botão Reportar erro padrão, no canto inferior direito.
O botão Reportar erro padrão, no canto inferior direito.
O formulário de relato: uma captura de tela marcada, o título e o que aconteceu.
O formulário de relato: uma captura de tela marcada, o título e o que aconteceu.

12Abra o formulário de relato a partir do seu próprio botão

Coloque o botão oficial em qualquer lugar com <BlipitReportButton />, também em server components: ele mostra o ícone do Blipit e Reportar erro no idioma do visitante e abre o formulário. Prefere o seu próprio design? O componente que chama openReport precisa ser um client component, então coloque "use client" no início do arquivo. <Blipit /> já precisa estar em app/layout.tsx. Apps React sem Next.js importam o botão de @blipit/nextjs/react e openReport de @blipit/browser.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
React sem 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>;
}
O botão oficial Reportar erro no cabeçalho de um site.
O botão oficial Reportar erro no cabeçalho de um site.
Um app Next.js: o botão personalizado Report Issue no cabeçalho abriu o formulário de relato do Blipit.
Um app Next.js: o botão personalizado Report Issue no cabeçalho abriu o formulário de relato do Blipit.

13Ocultar o botão padrão

Para manter só o seu próprio botão, desative o flutuante com feedbackWidget: false no código (feedbackWidget={false} em <Blipit />), ou desligue Mostrar o botão de relatório nas configurações do Widget de relatório de bugs do projeto para ocultá-lo em todos os sites que usam a chave. openReport() e attachReport() continuam funcionando de qualquer forma.

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

14Preencha o formulário de relato e adicione contexto

Chame setUser após o login: o nome e o e-mail de quem relata já vêm preenchidos, e essa pessoa recebe um e-mail quando você responde ou muda o status. setReportMetadata adiciona seus próprios campos, como o plano ou o tamanho do carrinho, a cada relatório; ele roda quando o relatório é enviado, então os valores estão sempre atualizados.

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

15Confira se funciona

Recarregue o app. O botão Reportar erro aparece no canto inferior direito e, em até um minuto, a visualização de página aparece em Web vitals no app.blipit.io. Depois adicione um botão que chama captureMessage, ou um que lança um erro, e clique nele: o evento aparece em Problemas em poucos 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>;
}

16Se o botão ou os eventos não aparecerem

  • Abra o console do navegador e procure linhas que começam com [blipit]. Ative o debug (debug: true no init, ou debug em <Blipit />) para ver se o botão foi exibido, desativado no código ou ocultado pela configuração do projeto.
  • O Next.js só envia ao navegador as variáveis cujo nome começa com NEXT_PUBLIC_, então use NEXT_PUBLIC_BLIPIT_KEY. O Vite só envia variáveis VITE_, então use VITE_BLIPIT_KEY. Com qualquer outro nome, a chave fica vazia no navegador e o Blipit não inicia.
  • Reinicie o servidor de desenvolvimento depois de adicionar ou alterar .env ou .env.local. Ele os lê apenas ao iniciar.
  • Na Vercel ou em qualquer outro host, adicione a mesma variável nas variáveis de ambiente do projeto e faça o deploy novamente. Os valores NEXT_PUBLIC_ e VITE_ são gravados no build, então um deploy em execução nunca vê um valor adicionado depois.
  • Use a chave pública (blipit_pk_). Uma chave secreta (blipit_sk_) é recusada no navegador com um erro no console; se alguma já esteve em uma página, crie uma nova chave secreta.
  • No Next.js, <Blipit /> vai no app/layout.tsx raiz (ou em pages/_app.tsx) para rodar em todas as páginas. Em outros apps, chame init uma única vez no arquivo de entrada, antes de o app renderizar.
  • Mostrar o botão de relatório precisa estar ativado no app.blipit.io, em Configurações do projeto, Widget de relatório de bugs, e o seu código não pode passar feedbackWidget: false. O SDK guarda as configurações do projeto por até uma hora, então teste uma alteração em uma janela anônima.
  • Bloqueadores de anúncios e extensões de privacidade podem bloquear in.blipit.io. Teste em uma janela anônima com as extensões desativadas.
  • Se o seu site envia uma Content Security Policy, permita script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: e media-src blob:. O editor do relato carrega de blipit.io/sdk no primeiro clique, a captura é desenhada a partir de uma imagem data: e as gravações de tela também são enviadas para in.blipit.io. Com debug ativado, o console avisa quando a política bloqueou a captura. Para que as gravações de tela tenham voz, o cabeçalho Permissions-Policy do site precisa permitir microphone=(self), e display-capture=(self) para a gravação de tela; com microphone=() as gravações funcionam sem som.
  • Confira a versão instalada com npm ls @blipit/browser @blipit/nextjs (ou pnpm list @blipit/browser @blipit/nextjs) e compare com o changelog. O pnpm 11 espera um dia antes de instalar uma versão nova (minimum-release-age), então no dia do lançamento o pnpm add instala a versão anterior sem avisar. Para pegar a nova na hora: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Travou? Envie um e-mail para support@blipit.io com as linhas [blipit] do console.

Bom saber

  • React simples sem Next.js: npm install @blipit/browser e chame Blipit.init antes de renderizar; veja Qualquer site.
  • Ambiente e release usam VERCEL_ENV e VERCEL_GIT_COMMIT_SHA como padrão no servidor quando você os omite.
  • Manter o Blipit atualizado: o guia Manter o Blipit atualizado (docs.blipit.io/updates) explica o banner de atualização, os e-mails de versões importantes, o aviso no seu console de desenvolvimento e o comando de atualização para esta plataforma.
  • Um projeto por app e plataforma: cada projeto escolhe a sua plataforma quando é criado (Android, iOS, React Native, Flutter, Web, Backend ou Odoo), e o Blipit recusa com um erro claro os dados de qualquer outra plataforma, por isso uma app iOS e uma app Android precisam de dois projetos com duas chaves. Releases, versões, taxas de falhas e builds das lojas são diferentes em cada plataforma, e misturá-los num projeto torna todos errados. Um projeto Web também aceita o lado servidor da mesma app web (o servidor Next.js ou Node), e um projeto React Native ou Flutter também aceita os seus próprios relatórios de falhas nativos de Android e iOS.

Travou? Envie um e-mail para support@blipit.io. As chaves e o id de cada projeto ficam em Chaves de API no app.blipit.io.