clerk-validator

Clerk Validator

Clerk の認証設定を検証し、Next.js 16 で最新の Clerk パターンを適用します。

このバリデーターが有効になるタイミング

• Clerk 認証をセットアップするとき
• 認証の実装作業を始める前
• 既存の Clerk 設定を監査するとき
• AI が Clerk コードを生成した後
• CI/CD パイプラインでの検証

クイックスタート

python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --strict

検証項目

1. パッケージのバージョン

// GOOD: Latest Clerk
"@clerk/nextjs": "^6.0.0"

// BAD: Old version
"@clerk/nextjs": "^4.0.0"

2. Proxy と Middleware（Next.js 16）

推奨 — Next.js 16：

// proxy.ts
import { clerkMiddleware } from "@clerk/nextjs/server";
export default clerkMiddleware();

非推奨のパターン：

// middleware.ts (deprecated in Next.js 16)
import { authMiddleware } from "@clerk/nextjs";  // DEPRECATED
export default authMiddleware();

3. ClerkProvider のセットアップ

推奨： アプリ全体を app/layout.tsx 内の <ClerkProvider> でラップします。 非推奨： _app.tsx（Pages Router、非推奨）に配置する、またはツリー全体を ラップし忘れること。

レイアウトの完全な例は references/full-guide.md（§ Clerk コンポーネントを含むルートレイアウト）を 参照してください。

4. 認証のインポートパターン

推奨 — サーバーサイド：

import { auth } from "@clerk/nextjs/server";

export default async function Page() {
  const { userId } = await auth();
  // ...
}

非推奨 — 古いパターン：

// Don't use
import { getAuth } from "@clerk/nextjs/server";  // OLD
import { currentUser } from "@clerk/nextjs";     // Check version

5. 環境変数

必須：

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

任意ですが、推奨：

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding

非推奨のパターン

非推奨	置き換え
authMiddleware()	clerkMiddleware()
middleware.ts	proxy.ts（Next.js 16）
getAuth()	auth()
@clerk/nextjs < v5	@clerk/nextjs@latest
_app.tsx のプロバイダー	app/layout.tsx のプロバイダー
withClerkMiddleware	clerkMiddleware()

検証結果

=== Clerk Validation Report ===
Package Version: @clerk/[email protected] ✓
Configuration: ✓ ClerkProvider  ✓ proxy.ts  ✗ middleware.ts found (deprecated)
Auth Patterns:  ✓ auth()  ✗ authMiddleware() in 1 file (deprecated)
Summary: 2 issues found

最新の Clerk パターン

保護されたルート（サーバーコンポーネント）

await auth() を呼び出し、userId がない場合は /sign-in にリダイレクトし、 その確認後にのみレンダリングします。

ページの完全な例は references/full-guide.md（§ 保護されたルートの例）を参照してください。

保護されたルート（クライアントコンポーネント）

コンポーネントに "use client" を指定し、useAuth() から { isLoaded, userId } を取得します。両方の値が確定するまでは、読み込み中またはリダイレクトの状態をレンダリングします。

コンポーネント全体の例は references/full-guide.md（§ Use Auth Hook）を参照してください。

API ルート

ルートハンドラー内で await auth() を呼び出し、userId がない場合は 処理を行う前に 401 を返します。

ハンドラー全体の例は references/full-guide.md（§ 保護された API ルート）を参照してください。

NestJS ガード

Bearer トークンを抽出し、clerkClient.verifyToken で検証して、 リクエストに userId を設定します。失敗した場合は false を返すか、例外をスローします。

ガード全体の例は references/full-guide.md（§ 認証ガード）を参照してください。

Webhook の設定

svix パッケージを使用して svix-id／svix-timestamp／svix-signature ヘッダーを CLERK_WEBHOOK_SECRET に照らして検証してから、ペイロードを信頼します。 検証されていない Webhook の本文は決して処理しないでください。

ルートハンドラー全体の例は references/full-guide.md（§ Webhooks（Next.js App Router））を、 NestJS コントローラーでの同等の実装は（§ Webhook Handler）を参照してください。

CI/CD への統合

# .github/workflows/validate.yml
- name: Validate Clerk Config
  run: |
    python3 scripts/validate.py \
      --root . \
      --strict \
      --ci

統合

• nextjs-validator — Next.js 16（proxy.ts）を検証します
• biome-validator — lint 設定を検証します
• git-safety — シークレットがコミットされないようにします