majiayu000 NextAuth.js Patterns
概要
NextAuth.js v5の設定とカスタマイズパターン。OAuth 2.0プロバイダー統合、データベースアダプター、セッション戦略、コールバック実装を扱う。
詳細な実装パターンと背景知識は references/ を参照。
ワークフロー
Phase 1: 要件整理とTask選択
目的: 実装要件を明確にし、適切なTaskを選択する
アクション:
- 実装要件を確認（OAuth provider, session strategy, database adapter）
references/basics.mdで基礎知識を確認- 必要に応じて以下のTaskを選択：
- 基本設定Task:
agents/config-setup.md- 初期auth.ts設定 - Provider統合Task:
agents/provider-integration.md- OAuth 2.0プロバイダー設定 - Session設計Task:
agents/session-design.md- セッション戦略とコールバック実装 - 検証Task:
agents/validation.md- 設定検証とテスト
- 基本設定Task:
Phase 2: Task実行
目的: 選択したTaskを順次実行する
Task呼び出しパターン:
# 基本設定から開始する場合
1. agents/config-setup.md → 基本auth.ts作成
2. agents/provider-integration.md → OAuth設定追加
3. agents/session-design.md → セッションコールバック実装
4. agents/validation.md → 動作確認
# 既存設定の拡張の場合
1. agents/provider-integration.md → 新規プロバイダー追加
2. agents/validation.md → 統合テスト
入出力契約:
- 入力: 要件定義（provider種別、session strategy、必須カスタマイズ）
- 中間成果物: auth.ts設定ファイル、環境変数設定
- 最終成果物: 動作確認済みの認証システム
Phase 3: 検証と記録
目的: 実装の検証と使用記録の保存
アクション:
scripts/validate-nextauth-config.mjsで設定を検証- 動作確認（ログイン/ログアウト/セッション取得）
scripts/log_usage.mjsで実行記録を保存
# 設定検証
node .claude/skills/nextauth-patterns/scripts/validate-nextauth-config.mjs <auth-file-path>
# 使用記録
node .claude/skills/nextauth-patterns/scripts/log_usage.mjs \
--result success \
--phase "provider-integration" \
--agent "provider-integration"
Task仕様ナビゲーション
agents/config-setup.md
いつ使うか: NextAuth.js初期セットアップ時
入力:
- プロジェクト構造（App Router / Pages Router）
- 使用データベース種別（PostgreSQL, MySQL, SQLite）
- 優先セッション戦略（JWT or Database）
出力:
auth.ts基本設定ファイル- Route Handler設定（
app/api/auth/[...nextauth]/route.ts） - 環境変数テンプレート（
.env.example）
agents/provider-integration.md
いつ使うか: OAuth 2.0プロバイダー追加時
入力:
- プロバイダー種別（Google, GitHub, その他）
- 必要スコープ
- カスタム認可パラメータ
出力:
- プロバイダー設定コード
- 環境変数追加項目
- OAuth コンソール設定手順
agents/session-design.md
いつ使うか: セッションカスタマイズが必要な場合
入力:
- カスタムセッションデータ（role, permissions, metadata等）
- セッション有効期限要件
- 更新トリガー条件
出力:
jwt()コールバック実装session()コールバック実装- TypeScript型定義拡張（
next-auth.d.ts）
agents/validation.md
いつ使うか: 実装完了後の検証フェーズ
入力:
- 実装済み
auth.ts - 環境変数設定（
.env.local） - テストシナリオ
出力:
- 検証レポート
- 問題点と修正提案
- セキュリティチェックリスト結果
ベストプラクティス
すべきこと
- 環境変数の分離: クライアントIDとシークレットは必ず
.env.localで管理 - 型安全性の確保:
next-auth.d.tsでセッション型を拡張 - セッション戦略の選択: JWT（スケーラビリティ優先）vs Database（即時無効化優先）を要件に応じて選択
- スコープの最小化: OAuth スコープは必要最小限に設定
- コールバックの分離: 複雑なロジックは別関数に切り出す
- 検証スクリプトの実行: 設定変更時は必ず
validate-nextauth-config.mjsを実行
避けるべきこと
- シークレットのハードコード: 環境変数を使わずコードに直接記述
- 過度なスコープ要求: 不要な権限を要求する
- 型定義の省略: any型でセッションを扱う
- エラーハンドリングの欠如: コールバック内でエラーを無視
- セッション期限の未設定: デフォルト値に依存する
- 検証の省略: 動作確認なしで本番デプロイ
リソース参照
参照ドキュメント
| ドキュメント | 内容 |
|---|---|
| references/basics.md | 基礎概念、認証フロー、コールバック |
| references/patterns.md | 実装パターン、アダプター統合 |
ドメイン知識
- Provider設定: references/provider-configurations.md
- Google, GitHub, その他OAuth 2.0プロバイダーの詳細設定
- Session & Callbacks: references/session-callbacks-guide.md
- jwt(), session(), signIn() 各コールバックの実装パターン
旧バージョン
- Legacy Skill: references/legacy-skill.md
- 旧SKILL.md全文（参考用）
スクリプト
validate-nextauth-config.mjs
目的: NextAuth.js設定ファイルの妥当性検証
使用法:
node scripts/validate-nextauth-config.mjs <auth-file-path>
検証項目:
- Provider設定の完全性
- 環境変数の存在確認
- Callback実装の型安全性
- Session戦略の一貫性
log_usage.mjs
目的: スキル使用記録と評価メトリクス更新
使用法:
node scripts/log_usage.mjs \
--result <success|failure> \
--phase "<phase-name>" \
--agent "<agent-name>" \
--notes "<optional-notes>"
validate-skill.mjs
目的: Skill構造の整合性検証
使用法:
node scripts/validate-skill.mjs
テンプレート
nextauth-config-template.ts
場所: assets/nextauth-config-template.ts
内容:
- Google/GitHub OAuth統合
- Drizzle Adapter設定
- JWT/Database session 両戦略
- Role-based session callback
使用法:
# テンプレート参照
cat .claude/skills/nextauth-patterns/assets/nextauth-config-template.ts
# プロジェクトにコピー
cp .claude/skills/nextauth-patterns/assets/nextauth-config-template.ts src/auth.ts
トラブルシューティング
よくある問題
| 問題 | 原因 | 解決策 |
|---|---|---|
NEXTAUTH_SECRET エラー |
環境変数未設定 | .env.local に追加、openssl rand -base64 32 で生成 |
| セッションに追加データが含まれない | Callback実装漏れ | jwt() と session() 両方で処理 |
| OAuth リダイレクトエラー | Redirect URI不一致 | Providerコンソールで http://localhost:3000/api/auth/callback/<provider> を登録 |
| 型エラー | next-auth.d.ts 未作成 |
Session/JWT型を拡張 |
評価基準
成功基準
- Provider認証が成功する
- セッションデータが正しく取得できる
- カスタムデータ（role等）がセッションに含まれる
- 型安全性が確保されている（TypeScriptエラーなし）
-
validate-nextauth-config.mjsが成功する
品質基準
- 環境変数が適切に分離されている
- コールバックロジックが明確で保守しやすい
- セッション戦略が要件に適合している
- OAuth スコープが最小限である
- エラーハンドリングが実装されている
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2025-12-31 | 18-skills.md準拠にリファクタリング、agents/追加 |
| 1.0.0 | 2025-12-24 | Spec alignment and required artifacts added |