All Skills > SDK Setup > Next.js SDK

Sentry Next.js SDK

Next.js プロジェクトをスキャンして、3つのランタイム（ブラウザ、Node.js サーバー、Edge）全体での完全な Sentry セットアップをガイドする意見的なウィザードです。

このスキルを呼び出すタイミング

• ユーザーが「Next.js に Sentry を追加する」または「Next.js アプリに Sentry をセットアップする」とリクエストしている
• ユーザーが @sentry/nextjs をインストールまたは構成したい
• ユーザーが Next.js でエラーモニタリング、トレーシング、セッションリプレイ、ログ、またはプロファイリングを望んでいる
• ユーザーが instrumentation.ts、withSentryConfig()、または global-error.tsx について質問している
• ユーザーがサーバーアクション、サーバーコンポーネントエラー、またはエッジランタイムエラーをキャプチャしたい

注記： 以下の SDK バージョンと API は、執筆時点での現在の Sentry ドキュメント（@sentry/nextjs ≥8.28.0）を反映しています。 実装前に必ず docs.sentry.io/platforms/javascript/guides/nextjs/ で確認してください。

---

フェーズ 1: 検出

推奨事項を行う前に、プロジェクトを理解するために以下のコマンドを実行します：

# Next.js バージョンと既存 Sentry を検出
cat package.json | grep -E '"next"|"@sentry/'

# ルータータイプ（App Router vs Pages Router）を検出
ls src/app app src/pages pages 2>/dev/null

# 既存 Sentry 設定ファイルを確認
ls instrumentation.ts instrumentation-client.ts sentry.server.config.ts sentry.edge.config.ts 2>/dev/null
ls src/instrumentation.ts src/instrumentation-client.ts 2>/dev/null

# next.config を確認
ls next.config.ts next.config.js next.config.mjs 2>/dev/null

# 既存エラーバウンダリを確認
find . -name "global-error.tsx" -o -name "_error.tsx" 2>/dev/null | grep -v node_modules

# ビルドツールを確認
cat package.json | grep -E '"turbopack"|"webpack"'

# ログライブラリを確認
cat package.json | grep -E '"pino"|"winston"|"bunyan"'

# コンパニオンバックエンドを確認
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

決定すること：

質問	影響
Next.js のバージョン？	13+ が必須；Turbopack サポートには 15+ が必要
App Router または Pages Router？	必要なエラーバウンダリファイルを決定（global-error.tsx vs _error.tsx）
@sentry/nextjs は既にありますか？	インストールをスキップ、機能設定に進む
既存の instrumentation.ts はありますか？	置き換えるのではなく Sentry をマージする
Turbopack を使用していますか？	withSentryConfig のツリーシェーキングは webpack のみ
ログライブラリを検出しましたか？	Sentry Logs インテグレーションをお勧めします
バックエンドディレクトリが見つかりましたか？	フェーズ 4 のクロスリンク提案をトリガー

---

フェーズ 2: 推奨

見つけたものに基づいて具体的な推奨事項を提示します。オープンエンドの質問はしないでください — 提案をリードしてください：

推奨（コアカバレッジ）:

• ✅ エラーモニタリング — 常に；サーバーエラー、クライアントエラー、サーバーアクション、ハンドルされない Promise 拒否をキャプチャします
• ✅ トレーシング — サーバー側リクエストトレーシング + すべてのランタイムでのクライアント側ナビゲーションスパン
• ✅ セッションリプレイ — ユーザー向けアプリに推奨；エラー周辺のセッションを記録します

オプション（強化されたオブザーバビリティ）:

• ⚡ ログ — Sentry.logger.* を経由した構造化ログ；pino/winston またはログ検索が必要な場合に推奨
• ⚡ プロファイリング — 継続的プロファイリング；Document-Policy: js-profiling ヘッダが必要です
• ⚡ AI モニタリング — OpenAI、Vercel AI SDK、Anthropic；AI/LLM 呼び出しが検出された場合に推奨
• ⚡ クロン — 逃したまたは失敗したスケジュールされたジョブを検出；クロンパターンが検出された場合に推奨
• ⚡ メトリクス — Sentry.metrics.* を経由したカスタムメトリクス；カスタム KPI またはビジネスメトリクスが必要な場合に推奨

推奨ロジック：

機能	推奨タイミング...
エラーモニタリング	常に — 非交渉のベースライン
トレーシング	常に Next.js の場合 — サーバールートトレーシング + クライアントナビゲーションは高価値
セッションリプレイ	ユーザー向けアプリ、ログインフロー、またはチェックアウトページ
ログ	アプリが構造化ログを使用するか、ログ対トレース相関が必要な場合
プロファイリング	パフォーマンス重視アプリ；クライアントが Document-Policy: js-profiling を設定する場合
AI モニタリング	アプリが OpenAI、Vercel AI SDK、または Anthropic を呼び出す場合
クロン	アプリが Vercel Cron ジョブ、スケジュールされた API ルート、または node-cron の使用がある場合
メトリクス	アプリが Sentry.metrics.* を経由したカスタムカウンター、ゲージ、またはヒストグラムが必要な場合

提案する：「エラーモニタリング + トレーシング + セッションリプレイのセットアップをお勧めします。ログまたはプロファイリングも追加したいですか？」

---

フェーズ 3: ガイド

オプション 1: ウィザード（推奨）

これは自分で実行する必要があります — ウィザードはブラウザでログインを開くため、エージェントが処理できない対話的入力が必要です。ターミナルにコピー&ペーストしてください：

npx @sentry/wizard@latest -i nextjs

ログイン、org/プロジェクト選択、SDK インストール、設定ファイル（instrumentation-client.ts、sentry.server.config.ts、sentry.edge.config.ts、instrumentation.ts）、next.config.ts ラッピング、ソースマップアップロード、/sentry-example-page の追加を処理します。

完了後、戻ってきて 検証 に進んでください。

ユーザーがウィザードをスキップした場合、以下の「オプション 2（手動セットアップ）」に進みます。

---

オプション 2: 手動セットアップ

インストール

npm install @sentry/nextjs --save

instrumentation-client.ts を作成 — ブラウザ / クライアントランタイム

古いドキュメントは sentry.client.config.ts を使用していました — 現在のパターンは instrumentation-client.ts です。

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN ?? "___PUBLIC_DSN___",

  sendDefaultPii: true,

  // 開発環境では 100%、本番環境では 10%
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // セッションリプレイ: 全セッションの 10%、エラーのあるセッションの 100%
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,

  integrations: [
    Sentry.replayIntegration(),
    // オプション: ユーザーフィードバックウィジェット
    // Sentry.feedbackIntegration({ colorScheme: "system" }),
  ],
});

// App Router ナビゲーション遷移にフック（App Router のみ）
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

sentry.server.config.ts を作成 — Node.js サーバーランタイム

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // スタックフレームにローカル変数値をアタッチ
  includeLocalVariables: true,

  enableLogs: true,
});

sentry.edge.config.ts を作成 — エッジランタイム

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  enableLogs: true,
});

instrumentation.ts を作成 — サーバー側登録フック

Next.js < 14.0.4 では next.config で experimental.instrumentationHook: true が必要です。14.0.4+ では安定しています。

import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }

  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// すべてのハンドルされないサーバー側リクエストエラーを自動的にキャプチャします
// @sentry/nextjs >= 8.28.0 が必要です
export const onRequestError = Sentry.captureRequestError;

ランタイムディスパッチ：

NEXT_RUNTIME	読み込まれる設定ファイル
"nodejs"	sentry.server.config.ts
"edge"	sentry.edge.config.ts
(クライアントバンドル)	instrumentation-client.ts （Next.js が直接処理）

App Router: app/global-error.tsx を作成

これはルートレイアウトと React レンダリングエラーをキャッチします：

"use client";

import * as Sentry from "@sentry/nextjs";
import NextError from "next/error";
import { useEffect } from "react";

export default function GlobalError({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <NextError statusCode={0} />
      </body>
    </html>
  );
}

Pages Router: pages/_error.tsx を更新

import * as Sentry from "@sentry/nextjs";
import type { NextPageContext } from "next";
import NextErrorComponent from "next/error";

type ErrorProps = { statusCode: number };

export default function CustomError({ statusCode }: ErrorProps) {
  return <NextErrorComponent statusCode={statusCode} />;
}

CustomError.getInitialProps = async (ctx: NextPageContext) => {
  await Sentry.captureUnderscoreErrorException(ctx);
  return NextErrorComponent.getInitialProps(ctx);
};

next.config.ts を withSentryConfig() でラップ

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  // 既存の Next.js 設定
};

export default withSentryConfig(nextConfig, {
  org: "___ORG_SLUG___",
  project: "___PROJECT_SLUG___",

  // ソースマップアップロード認証トークン（以下の「ソースマップ」セクションを参照）
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // より良いスタックトレース解決のためにより広いセットのクライアントソースファイルをアップロード
  widenClientFileUpload: true,

  // 広告ブロッカーをバイパスするためにプロキシ API ルートを作成
  tunnelRoute: "/monitoring",

  // CI 以外の出力を抑制
  silent: !process.env.CI,
});

トンネルルートをミドルウェアから除外

middleware.ts がある場合、認証またはリダイレクトロジックからトンネルパスを除外します：

// middleware.ts
export const config = {
  matcher: [
    // 監視ルート、Next.js インターナル、静的ファイルを除外
    "/((?!monitoring|_next/static|_next/image|favicon.ico).*)",
  ],
};

---

ソースマップセットアップ

ソースマップは本番環境のスタックトレースを読みやすくします — ソースマップなしでは、ミニ化されたコードが表示されます。本番環境アプリではこれは必須です。

ステップ 1: Sentry 認証トークンを生成

sentry.io/settings/auth-tokens/ に移動して、project:releases および org:read スコープを持つトークンを作成します。

ステップ 2: 環境変数を設定

# .env.sentry-build-plugin  (このファイルを gitignore する)
SENTRY_AUTH_TOKEN=sntrys_eyJ...

または CI シークレットで設定：

SENTRY_AUTH_TOKEN=sntrys_eyJ...
SENTRY_ORG=my-org        # next.config で設定されている場合はオプション
SENTRY_PROJECT=my-project # next.config で設定されている場合はオプション

ステップ 3: .gitignore に追加

.env.sentry-build-plugin

ステップ 4: authToken が next.config.ts で接続されていることを確認

withSentryConfig(nextConfig, {
  org: "my-org",
  project: "my-project",
  authToken: process.env.SENTRY_AUTH_TOKEN, // .env.sentry-build-plugin または CI env から読み込む
  widenClientFileUpload: true,
});

ソースマップは next build のたびに自動的にアップロードされます。

---

合意された各機能の場合

対応するリファレンスファイルをロードして、その手順に従います：

機能	リファレンスファイル	読み込みタイミング...
エラーモニタリング	references/error-monitoring.md	常に（ベースライン） — App Router エラーバウンダリ、Pages Router _error.tsx、サーバーアクションラッピング
トレーシング	references/tracing.md	サーバー側リクエストトレーシング、クライアントナビゲーション、分散トレーシング、tracePropagationTargets
セッションリプレイ	references/session-replay.md	ユーザー向けアプリ；プライバシーマスキング、キャンバス記録、ネットワークキャプチャ
ログ	references/logging.md	構造化ログ、Sentry.logger.*、ログ対トレース相関
プロファイリング	references/profiling.md	継続的プロファイリング、Document-Policy ヘッダ、nodeProfilingIntegration
AI モニタリング	references/ai-monitoring.md	アプリが OpenAI、Vercel AI SDK、または Anthropic を使用する場合
クロン	references/crons.md	Vercel Cron、スケジュールされた API ルート、node-cron
メトリクス	references/metrics.md	Sentry.metrics.* を経由したカスタムカウンター、ゲージ、分布

各機能について：リファレンスファイルを読み、その手順に正確に従い、次に進む前に検証します。

---

検証

ウィザードまたは手動セットアップの後、Sentry が機能していることを確認します：

// サーバーアクションまたは API ルートに一時的に追加してから削除
import * as Sentry from "@sentry/nextjs";

throw new Error("Sentry test error — delete me");
// または
Sentry.captureException(new Error("Sentry test error — delete me"));

その後、Sentry Issues ダッシュボード をチェック — エラーは ~30 秒以内に表示されるはずです。

検証チェックリスト：

チェック	方法
クライアントエラーがキャプチャされた	クライアントコンポーネントでスロー、Sentry で検証
サーバーエラーがキャプチャされた	サーバーアクションまたは API ルートでスロー
エッジエラーがキャプチャされた	ミドルウェアまたはエッジルートハンドラーでスロー
ソースマップが機能している	スタックトレースが読み可能なファイル名を表示することを確認
セッションリプレイが機能している	Sentry ダッシュボードの「Replays」タブをチェック

---

設定リファレンス

Sentry.init() オプション

オプション	タイプ	デフォルト	注記
dsn	string	—	必須。クライアントには NEXT_PUBLIC_SENTRY_DSN、サーバーには SENTRY_DSN を使用
tracesSampleRate	number	—	0–1；開発環境は 1.0、本番環境は 0.1 推奨
replaysSessionSampleRate	number	0.1	記録される全セッションの割合
replaysOnErrorSampleRate	number	1.0	記録されるエラーセッションの割合
sendDefaultPii	boolean	false	イベントに IP、リクエストヘッダを含める
includeLocalVariables	boolean	false	ローカル変数値をスタックフレームにアタッチ（サーバーのみ）
enableLogs	boolean	false	Sentry Logs プロダクトを有効化
environment	string	自動	"production"、"staging" など
release	string	自動	コミット SHA またはバージョンタグに設定
debug	boolean	false	SDK アクティビティをコンソールにログ

withSentryConfig() オプション

オプション	タイプ	注記
org	string	Sentry 組織スラッグ
project	string	Sentry プロジェクトスラッグ
authToken	string	ソースマップアップロードトークン（SENTRY_AUTH_TOKEN）
widenClientFileUpload	boolean	より良いスタックトレースのためにより多くのクライアントファイルをアップロード
tunnelRoute	string	広告ブロッカーをバイパスするための API ルートパス（例 "/monitoring"）
silent	boolean	ビルド出力を抑制（!process.env.CI 推奨）
webpack.treeshake.*	object	SDK 機能をツリーシェーク（webpack のみ、Turbopack ではない）

環境変数

変数	ランタイム	目的
NEXT_PUBLIC_SENTRY_DSN	クライアント	ブラウザ Sentry init 用の DSN（公開）
SENTRY_DSN	サーバー / エッジ	サーバー/エッジ Sentry init 用の DSN
SENTRY_AUTH_TOKEN	ビルド	ソースマップアップロード認証トークン（シークレット）
SENTRY_ORG	ビルド	Org スラッグ（設定の org の代替）
SENTRY_PROJECT	ビルド	プロジェクトスラッグ（設定の project の代替）
SENTRY_RELEASE	サーバー	リリースバージョン文字列（git から自動検出）
NEXT_RUNTIME	サーバー / エッジ	"nodejs" または "edge"（Next.js が内部的に設定）

---

フェーズ 4: クロスリンク

Next.js セットアップが完了した後、コンパニオンサービスをチェック：

# 隣接ディレクトリ内のバックエンドサービスを確認
ls ../backend ../server ../api ../services 2>/dev/null

# バックエンド言語インジケーターを確認
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml ../build.gradle 2>/dev/null | head -3

バックエンドが見つかった場合、マッチングする SDK スキルを提案：

バックエンド検出	スキルを提案
Go (go.mod)	sentry-go-sdk
Python (requirements.txt, pyproject.toml)	sentry-python-sdk
Ruby (Gemfile)	sentry-ruby-sdk
Java/Kotlin (pom.xml, build.gradle)	docs.sentry.io/platforms/java/ を参照
Node.js (Express、Fastify、Hapi)	@sentry/node — docs.sentry.io/platforms/javascript/guides/express/ を参照

フロントエンドとバックエンドを同じ DSN またはリンクされたプロジェクトで接続すると、分散トレーシングが有効になります — ブラウザ、Next.js サーバー、バックエンド API にまたがるスタックトレースが単一のトレースビューに表示されます。

---

トラブルシューティング

問題	原因	解決策
イベントが表示されない	DSN が設定されていないか debug: false がエラーを隠している	一時的に debug: true を設定；ブラウザネットワークタブで sentry.io へのリクエストを確認
スタックトレースがミニ化されたコードを表示	ソースマップがアップロードされていない	SENTRY_AUTH_TOKEN が設定されていることを確認；next build を実行してビルド出力の「Source Maps」を確認
onRequestError が動作していない	SDK バージョン < 8.28.0	アップグレード：npm install @sentry/nextjs@latest
エッジランタイムエラーがない	sentry.edge.config.ts が読み込まれていない	NEXT_RUNTIME === "edge" のときに instrumentation.ts がこれをインポートしていることを確認
トンネルルートが 404 を返す	tunnelRoute は設定されているが Next.js ルートがない	プラグインが自動作成するはず；tunnelRoute を追加後に next build を実行したことを確認
withSentryConfig ツリーシェーキングでビルドが壊れる	Turbopack が使用されている	ツリーシェーキングオプションは webpack でのみ機能；Turbopack 使用時に webpack.treeshake オプションを削除
global-error.tsx がエラーをキャッチしていない	"use client" ディレクティブが不足している	"use client" を global-error.tsx の最初の行に追加
セッションリプレイが記録されていない	クライアント init に replayIntegration() がない	instrumentation-client.ts の integrations に Sentry.replayIntegration() を追加