| name | nextauth-patterns |
| description | NextAuth.js v5の設定とカスタマイズパターンを専門とするスキル。
OAuth 2.0プロバイダー統合、データベースアダプター、セッション戦略、コールバック実装、型安全なセッション管理を提供する。
Anchors:
• Web Application Security (Andrew Hoffman) / 適用: OAuth脅威モデリングとセッションセキュリティ / 目的: 安全な認証フロー設計
• NextAuth.js v5 Official Docs / 適用: プロバイダー設定とコールバック / 目的: 標準準拠の実装
Trigger:
Use when implementing NextAuth.js authentication, configuring OAuth providers (Google, GitHub),
integrating database adapters (Drizzle), designing session strategies (JWT or database-backed),
customizing authentication callbacks, or adding role-based data to sessions.
Keywords: nextauth, oauth, authentication, session, jwt, drizzle adapter, google oauth, github oauth
|
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 - 設定検証とテスト
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型でセッションを扱う
- エラーハンドリングの欠如: コールバック内でエラーを無視
- セッション期限の未設定: デフォルト値に依存する
- 検証の省略: 動作確認なしで本番デプロイ
リソース参照
参照ドキュメント
ドメイン知識
旧バージョン
スクリプト
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型を拡張 |
評価基準
成功基準
品質基準
変更履歴
| 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 |
