Next.js と React

インストール npm install @blipit/nextjs

@blipit/nextjs を使うと、レイアウトに置いた1つのコンポーネントでブラウザのエラー、Web Vitals、セッションリプレイ、「不具合を報告」ボタンを、instrumentation.ts の1行でサーバーコンポーネント、ルートハンドラー、サーバーアクションのエラーを取得できます。通常の React アプリでは @blipit/browser を使います。

Claude Code、Cursor などのAIコーディングアシスタントに貼り付けてください。手順とコードが含まれています。app.blipit.io の「APIキー」では、キーが入力済みの同じプロンプトをコピーできます。
動画:どのスタックにも Blipit を導入(0:32 から)

1インストール

sh
npm install @blipit/nextjs

2キーを取得

app.blipit.io にサインインし、サイドバーの「APIキー」を開いてプロジェクトを選びます。各プロジェクトには2つのキーがあります。公開キーは blipit_pk_ で始まり、ブラウザやアプリのコードに置くものです。イベントの送信しかできないため、誰に見られても安全です。シークレットキーは blipit_sk_ で始まり、サーバーまたは Odoo に置き、ブラウザには決して置きません。イシューの読み取りや変更もできるためです。シークレットキーは作成直後に一度だけ表示されるので、そのときにコピーしてください。紛失した場合は「新しいシークレットキーを作成」を押すと、古いキーは即座に無効になります。一部の SDK では、同じページに表示されるプロジェクト ID も必要です。

app.blipit.io の API キー:ブラウザコード用の公開キー(blipit_pk_)と、サーバーおよび Odoo 用のシークレットキー(blipit_sk_)。
app.blipit.io の API キー:ブラウザコード用の公開キー(blipit_pk_)と、サーバーおよび Odoo 用のシークレットキー(blipit_sk_)。
新しいシークレットキーは一度だけ表示されます。今すぐコピーしてください。ハッシュ化して保存されるため、再表示はできません。
新しいシークレットキーは一度だけ表示されます。今すぐコピーしてください。ハッシュ化して保存されるため、再表示はできません。

3キーを .env.local に置く

プロジェクトのルートに .env.local を作成し、ブラウザ用の公開キーと、後述のサーバー側を使う場合はサーバー用のシークレットキーを記述します。ブラウザに届くのは NEXT_PUBLIC_ で始まる名前だけなので、シークレットキーには決してこのプレフィックスを付けないでください。ファイルを保存したら npm run dev を再起動します。本番環境では、ホスティング先に同じ変数を追加し(Vercel の場合:Project、Settings、Environment Variables で Production と Preview に追加)、再度デプロイします。NEXT_PUBLIC_ の値はビルドに書き込まれるため、変数を追加する前に作成したデプロイではキーが空になります。

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4ブラウザ側

ルートレイアウトにコンポーネントを1回追加します。公開キーは NEXT_PUBLIC_BLIPIT_KEY から読み込まれます。変数が空の場合は何も起動せず、その旨をブラウザのコンソールに表示します。

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

5サーバー側

Next.js 15 以降は、サーバーコンポーネント、ルートハンドラー、サーバーアクションのエラーで onRequestError を呼び出します。instrumentation.ts の1行で Blipit に接続できます。@blipit/nextjs 0.2.1 以降は、middleware.ts があるアプリや Edge ルート(runtime = "edge")でも同じ1行が動作します。アプリはビルドでき、ミドルウェアと Edge のエラーも報告されます。Next.js 14 には onRequestError がないため、2つ目の例のように各ルートハンドラーとサーバーアクションを withBlipit で囲んでください。エラーを報告してから再度スローし、リダイレクトと notFound() は除外します。BLIPIT_SECRET_KEY はサーバー環境に設定し、決して 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());
});

6依存サービスとサーバーの状態

@blipit/nextjs 0.3 からは register もエクスポートして、サーバー起動時に Blipit を開始します。データベースや外部サービスへの呼び出しが依存サービスのページに、サーバーの CPU、メモリ、イベントループがサーバーの状態に記録されます。Edge ランタイムでは何もしません。 Vercel では register が受信リクエストを見られないことがあります。@blipit/nextjs 0.4 からは、ルートハンドラーとサーバーアクションを withBlipit でラップすると、それぞれがデータベースや外部サービスの呼び出しとともに Pulse ページのリクエストになり、応答の後に送信されるので応答は遅れません。

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

7error.tsx で捕捉されたエラー

error.tsx や global-error.tsx の境界で捕捉されたエラーはブラウザのエラーハンドラーに届かないため、境界から報告してください。どちらのファイルもクライアントコンポーネントです。

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

8キーを git に含めない

キーは環境変数またはホスティング先のシークレット設定に保管し、コミットするコードには決して書かないでください。また、.env ファイルを .gitignore に追加してください。Web ページに公開キーがあるのは通常のことです。シークレットキーが git、公開ページ、スクリーンショット、チャットなどに漏れた場合は、「APIキー」を開いて「新しいシークレットキーを作成」を押し、古いキーを使っていた箇所すべてに新しいキーを貼り付けてください。古いキーは即座に無効になります。

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

9Content Security Policy

サイトが Content Security Policy を送信している場合は、script-src https://blipit.io(script タグと、初回使用時に blipit.io/sdk/<version>/ から読み込まれるレポーターエディターとリプレイアドオン)、connect-src https://in.blipit.io(イベント、スクリーンショット、画面録画はすべて in.blipit.io に送られます)、img-src data:(スクリーンショットはページの画像から描画されます)、media-src blob:(録画はレポーター内で再生されます)を許可してください。スクリーンショットはページの画像とフォントを読み込み直すため、それらのホストも connect-src に含めてください。含めないと空白になります。style-src の変更は不要です。script タグを使う場合は、厳格なポリシーではインラインスクリプトがブロックされるため、Blipit.init を独自の .js ファイルから呼び出すか、インラインスクリプトに nonce を付けてください。 画面録画に音声を入れるには、サイトの Permissions-Policy ヘッダーで microphone=(self) を、画面録画には display-capture=(self) を許可してください。microphone=() の場合、録画は音声なしで動作します。

10ソースマップ(任意)

スタックトレースに縮小化されたバンドルではなくソースが表示されるよう、ビルドステップから各 release のマップをアップロードしてください。

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

11バグレポート:「不具合を報告」ボタン

公開キーで SDK が起動すると、すべてのページの右下に訪問者の言語で「不具合を報告」ボタンが表示されます。クリックするとレポーターが開き、ページのスクリーンショットへの書き込み、要素の選択、任意の画面録画、タイトルと説明の入力ができます。位置、スタイル、テキスト、色、キーボードショートカットは、以下のようにコードで変更するか、app.blipit.io の「プロジェクト設定」→「バグレポートウィジェット」ですべてのサイトに一括で変更できます。コードのオプションが優先されます。バグレポートボタンのガイドでは、すべてのオプションをスクリーンショットとライブデモ付きで紹介しています。

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",
  }}
/>
右下にあるデフォルトの「不具合を報告」ボタン。
右下にあるデフォルトの「不具合を報告」ボタン。
レポーター:書き込み済みのスクリーンショット、タイトル、何が起きたか。
レポーター:書き込み済みのスクリーンショット、タイトル、何が起きたか。

12独自のボタンからレポーターを開く

<BlipitReportButton /> で公式ボタンをどこにでも置けます。サーバーコンポーネントでも使えます。Blipit アイコンと訪問者の言語の「不具合を報告」を表示し、レポーターを開きます。独自のデザインにしたい場合、openReport を呼び出すコンポーネントはクライアントコンポーネントである必要があるため、ファイルの先頭に "use client" を記述します。<Blipit /> はあらかじめ app/layout.tsx に置いておく必要があります。Next.js を使わない React アプリでは、ボタンを @blipit/nextjs/react から、openReport を @blipit/browser からインポートします。

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
Next.js を使わない React
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>;
}
サイトのヘッダーに置いた公式の「不具合を報告」ボタン。
サイトのヘッダーに置いた公式の「不具合を報告」ボタン。
Next.js アプリ:ヘッダーのカスタム Report Issue ボタンで Blipit のレポーターが開いた状態。
Next.js アプリ:ヘッダーのカスタム Report Issue ボタンで Blipit のレポーターが開いた状態。

13デフォルトのボタンを隠す

独自のボタンだけを残すには、コードで feedbackWidget: false(<Blipit /> では feedbackWidget={false})を指定してフローティングボタンをオフにするか、プロジェクトの「バグレポートウィジェット」設定で「バグレポートボタンを表示」をオフにして、このキーを使うすべてのサイトで非表示にします。どちらの場合も openReport() と attachReport() は引き続き動作します。

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

14レポーターへの事前入力とコンテキストの追加

サインイン後に setUser を呼び出すと、報告者の名前とメールアドレスが入力済みになり、返信やステータス変更の際に報告者へメールが届きます。setReportMetadata は、プランやカートのサイズなど独自のフィールドをすべてのレポートに追加します。レポートの送信時に実行されるため、値は常に最新です。

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

15動作確認

アプリを再読み込みします。右下に「不具合を報告」ボタンが表示され、1分以内に app.blipit.io の「Web Vitals」にページビューが表示されます。次に captureMessage を呼び出すボタンか例外をスローするボタンを追加してクリックすると、数秒以内に「イシュー」にイベントが表示されます。

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

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

16ボタンやイベントが表示されない場合

  • ブラウザのコンソールを開き、[blipit] で始まる行を探してください。debug をオンにすると(init で debug: true、または <Blipit /> に debug)、ボタンが表示されたか、コードでオフにされたか、プロジェクトの設定で非表示になったかを確認できます。
  • Next.js がブラウザに送るのは名前が NEXT_PUBLIC_ で始まる変数だけなので、NEXT_PUBLIC_BLIPIT_KEY を使います。Vite が送るのは VITE_ 変数だけなので、VITE_BLIPIT_KEY を使います。それ以外の名前ではブラウザでキーが空になり、Blipit は起動しません。
  • .env や .env.local を追加・変更したら開発サーバーを再起動してください。これらは起動時にのみ読み込まれます。
  • Vercel などのホスティング先では、プロジェクトの環境変数に同じ変数を追加して再度デプロイします。NEXT_PUBLIC_ と VITE_ の値はビルドに書き込まれるため、後から追加した値は実行中のデプロイには反映されません。
  • 公開キー(blipit_pk_)を使ってください。シークレットキー(blipit_sk_)はブラウザでコンソールエラーとともに拒否されます。シークレットキーがページに置かれたことがある場合は、新しいシークレットキーを作成してください。
  • Next.js では、すべてのページで動作するよう <Blipit /> をルートの app/layout.tsx(または pages/_app.tsx)に置きます。その他のアプリでは、アプリの描画前にエントリーファイルで init を1回呼び出します。
  • app.blipit.io の「プロジェクト設定」→「バグレポートウィジェット」で「バグレポートボタンを表示」がオンになっていること、またコードで feedbackWidget: false を渡していないことを確認してください。SDK はプロジェクト設定を最大1時間保持するため、変更はプライベートウィンドウでテストしてください。
  • 広告ブロッカーやプライバシー拡張機能が in.blipit.io をブロックすることがあります。拡張機能をオフにしたプライベートウィンドウで試してください。
  • サイトが Content Security Policy を送信している場合は、script-src https://blipit.io、connect-src https://in.blipit.io、img-src data:、media-src blob: を許可してください。レポーターエディターは初回クリック時に blipit.io/sdk から読み込まれ、スクリーンショットは data: 画像から描画され、画面録画も in.blipit.io にアップロードされます。debug をオンにすると、ポリシーがスクリーンショットをブロックしたときにコンソールに表示されます。 画面録画に音声を入れるには、サイトの Permissions-Policy ヘッダーで microphone=(self) を、画面録画には display-capture=(self) を許可してください。microphone=() の場合、録画は音声なしで動作します。
  • インストールされているバージョンを npm ls @blipit/browser @blipit/nextjs(または pnpm list @blipit/browser @blipit/nextjs)で確認し、変更履歴と比べてください。pnpm 11 は新しいリリースをインストールする前に 1 日待つ(minimum-release-age)ため、リリース当日の pnpm add は何も知らせずに前のバージョンをインストールします。新しいバージョンをすぐに入れるには pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0 を実行します。
  • それでも解決しない場合は、コンソールの [blipit] の行を添えて support@blipit.io までメールしてください。

知っておくと便利

  • Next.js を使わない通常の React:npm install @blipit/browser を実行し、レンダリング前に Blipit.init を呼び出します。「任意の Web サイト」を参照してください。
  • environment と release を省略すると、サーバーでは VERCEL_ENV と VERCEL_GIT_COMMIT_SHA がデフォルトになります。
  • Blipit を最新に保つ:「Blipit を最新に保つ」ガイド(docs.blipit.io/updates)で、更新バナー、重要なリリースのメール、開発コンソールのお知らせ、このプラットフォームの更新コマンドを説明しています。
  • アプリとプラットフォームごとに 1 つのプロジェクト:各プロジェクトは作成時にプラットフォーム(Android、iOS、React Native、Flutter、Web、Backend、Odoo)を選び、Blipit はほかのプラットフォームからのデータをわかりやすいエラーで拒否します。そのため iOS アプリと Android アプリには、キーが別々の 2 つのプロジェクトが必要です。リリース、バージョン、クラッシュ率、ストア向けビルドはプラットフォームごとに異なり、1 つのプロジェクトに混ぜるとすべての数字が正しくなくなります。Web プロジェクトは同じ Web アプリのサーバー側(Next.js サーバーや Node)も受け付け、React Native と Flutter のプロジェクトは自身の Android と iOS のネイティブクラッシュレポートも受け付けます。

お困りですか?support@blipit.io までメールしてください。各プロジェクトのキーとプロジェクト ID は app.blipit.io の「APIキー」にあります。