clerk-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clerk Validator

Clerk 验证器

Validates Clerk authentication configuration and prevents deprecated patterns. AI assistants often generate old Clerk patterns - this skill enforces modern Clerk with Next.js 16.

验证Clerk认证配置并防止使用已弃用的模式。AI助手经常生成旧版Clerk代码模式——本工具确保在Next.js 16中使用现代化的Clerk实现。

When This Activates

触发场景

Setting up Clerk authentication
Before any auth implementation work
Auditing existing Clerk configuration
After AI generates Clerk code
CI/CD pipeline validation

配置Clerk认证时
开始任何认证实现工作前
审计现有Clerk配置时
AI生成Clerk代码后
CI/CD流水线验证环节

Quick Start

快速开始

bash

python3 ~/.claude/skills/clerk-validator/scripts/validate.py --root .
python3 ~/.claude/skills/clerk-validator/scripts/validate.py --root . --strict

bash

python3 ~/.claude/skills/clerk-validator/scripts/validate.py --root .
python3 ~/.claude/skills/clerk-validator/scripts/validate.py --root . --strict

What Gets Checked

检查内容

1. Package Version

1. 包版本

json

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

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

json

// 正确：最新版Clerk
"@clerk/nextjs": "^6.0.0"

// 错误：旧版本
"@clerk/nextjs": "^4.0.0"

2. Proxy vs Middleware (Next.js 16)

2. Proxy与Middleware对比（Next.js 16）

GOOD - Next.js 16:

typescript

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

BAD - Deprecated:

typescript

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

正确 - Next.js 16：

typescript

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

错误 - 已弃用：

typescript

// middleware.ts (Next.js 16中已弃用)
import { authMiddleware } from "@clerk/nextjs";  // 已弃用
export default authMiddleware();

3. ClerkProvider Setup

3. ClerkProvider配置

GOOD:

typescript

// app/layout.tsx
import { ClerkProvider } from "@clerk/nextjs";

export default function RootLayout({ children }) {
  return (
    <ClerkProvider>
      <html>
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

BAD - Missing or wrong location:

typescript

// Don't put in _app.tsx (Pages Router deprecated)
// Don't forget to wrap the entire app

正确：

typescript

// app/layout.tsx
import { ClerkProvider } from "@clerk/nextjs";

export default function RootLayout({ children }) {
  return (
    <ClerkProvider>
      <html>
        <body>{children}</body>
      </html>
    </ClerkProvider>
  );
}

错误 - 缺失或位置错误：

typescript

// 不要放在_app.tsx中（Pages Router已弃用）
// 不要忘记包裹整个应用

4. Auth Import Patterns

4. 认证导入模式

GOOD - Server-side:

typescript

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

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

BAD - Old patterns:

typescript

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

正确 - 服务端：

typescript

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

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

错误 - 旧模式：

typescript

// 请勿使用
import { getAuth } from "@clerk/nextjs/server";  // 旧版
import { currentUser } from "@clerk/nextjs";     // 请检查版本

5. Environment Variables

5. 环境变量

Required:

env

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

Optional but recommended:

env

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

必填：

env

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

可选但推荐配置：

env

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

Deprecated Patterns

已弃用模式

Deprecated	Replacement
`authMiddleware()`	`clerkMiddleware()`
`middleware.ts`	`proxy.ts` (Next.js 16)
`getAuth()`	`auth()`
`@clerk/nextjs` < v5	`@clerk/nextjs@latest`
`_app.tsx` provider	`app/layout.tsx` provider
`withClerkMiddleware`	`clerkMiddleware()`

已弃用内容	替代方案
`authMiddleware()`	`clerkMiddleware()`
`middleware.ts`	`proxy.ts` (Next.js 16)
`getAuth()`	`auth()`
`@clerk/nextjs` < v5	`@clerk/nextjs@latest`
`_app.tsx` 中的provider	`app/layout.tsx` 中的provider
`withClerkMiddleware`	`clerkMiddleware()`

Validation Output

验证输出

=== Clerk Validation Report ===

Package Version: @clerk/nextjs@6.0.0 ✓

Configuration:
  ✓ ClerkProvider in app/layout.tsx
  ✓ proxy.ts with clerkMiddleware
  ✗ Found middleware.ts - should use proxy.ts for Next.js 16
  ✓ Environment variables configured

Auth Patterns:
  ✓ Using auth() from @clerk/nextjs/server
  ✗ Found deprecated authMiddleware() in 1 file

Summary: 2 issues found

=== Clerk Validation Report ===

Package Version: @clerk/nextjs@6.0.0 ✓

Configuration:
  ✓ ClerkProvider in app/layout.tsx
  ✓ proxy.ts with clerkMiddleware
  ✗ Found middleware.ts - should use proxy.ts for Next.js 16
  ✓ Environment variables configured

Auth Patterns:
  ✓ Using auth() from @clerk/nextjs/server
  ✗ Found deprecated authMiddleware() in 1 file

Summary: 2 issues found

Modern Clerk Patterns

现代化Clerk模式

Protected Routes (Server Component)

受保护路由（服务端组件）

typescript

// app/dashboard/page.tsx
import { auth } from "@clerk/nextjs/server";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const { userId } = await auth();

  if (!userId) {
    redirect("/sign-in");
  }

  return <Dashboard />;
}

typescript

// app/dashboard/page.tsx
import { auth } from "@clerk/nextjs/server";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const { userId } = await auth();

  if (!userId) {
    redirect("/sign-in");
  }

  return <Dashboard />;
}

Protected Routes (Client Component)

受保护路由（客户端组件）

typescript

"use client";
import { useAuth } from "@clerk/nextjs";

export default function ProtectedComponent() {
  const { isLoaded, userId } = useAuth();

  if (!isLoaded) return <Loading />;
  if (!userId) return <Redirect to="/sign-in" />;

  return <Content />;
}

typescript

"use client";
import { useAuth } from "@clerk/nextjs";

export default function ProtectedComponent() {
  const { isLoaded, userId } = useAuth();

  if (!isLoaded) return <Loading />;
  if (!userId) return <Redirect to="/sign-in" />;

  return <Content />;
}

API Routes

API路由

typescript

// app/api/protected/route.ts
import { auth } from "@clerk/nextjs/server";
import { NextResponse } from "next/server";

export async function GET() {
  const { userId } = await auth();

  if (!userId) {
    return new NextResponse("Unauthorized", { status: 401 });
  }

  return NextResponse.json({ userId });
}

typescript

// app/api/protected/route.ts
import { auth } from "@clerk/nextjs/server";
import { NextResponse } from "next/server";

export async function GET() {
  const { userId } = await auth();

  if (!userId) {
    return new NextResponse("Unauthorized", { status: 401 });
  }

  return NextResponse.json({ userId });
}

NestJS Guard

typescript

// auth/clerk.guard.ts
import { Injectable, CanActivate, ExecutionContext } from "@nestjs/common";
import { clerkClient } from "@clerk/clerk-sdk-node";

@Injectable()
export class ClerkGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractToken(request);

    if (!token) return false;

    try {
      const { userId } = await clerkClient.verifyToken(token);
      request.userId = userId;
      return true;
    } catch {
      return false;
    }
  }

  private extractToken(request: any): string | null {
    const auth = request.headers.authorization;
    if (!auth?.startsWith("Bearer ")) return null;
    return auth.slice(7);
  }
}

typescript

// auth/clerk.guard.ts
import { Injectable, CanActivate, ExecutionContext } from "@nestjs/common";
import { clerkClient } from "@clerk/clerk-sdk-node";

@Injectable()
export class ClerkGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractToken(request);

    if (!token) return false;

    try {
      const { userId } = await clerkClient.verifyToken(token);
      request.userId = userId;
      return true;
    } catch {
      return false;
    }
  }

  private extractToken(request: any): string | null {
    const auth = request.headers.authorization;
    if (!auth?.startsWith("Bearer ")) return null;
    return auth.slice(7);
  }
}

Webhook Configuration

Webhook配置

typescript

// app/api/webhooks/clerk/route.ts
import { Webhook } from "svix";
import { headers } from "next/headers";
import { WebhookEvent } from "@clerk/nextjs/server";

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;
  if (!WEBHOOK_SECRET) throw new Error("Missing CLERK_WEBHOOK_SECRET");

  const headerPayload = headers();
  const svix_id = headerPayload.get("svix-id");
  const svix_timestamp = headerPayload.get("svix-timestamp");
  const svix_signature = headerPayload.get("svix-signature");

  const body = await req.text();
  const wh = new Webhook(WEBHOOK_SECRET);
  const evt = wh.verify(body, {
    "svix-id": svix_id!,
    "svix-timestamp": svix_timestamp!,
    "svix-signature": svix_signature!,
  }) as WebhookEvent;

  // Handle event
  switch (evt.type) {
    case "user.created":
      // Sync to database
      break;
  }

  return new Response("OK", { status: 200 });
}

typescript

// app/api/webhooks/clerk/route.ts
import { Webhook } from "svix";
import { headers } from "next/headers";
import { WebhookEvent } from "@clerk/nextjs/server";

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;
  if (!WEBHOOK_SECRET) throw new Error("Missing CLERK_WEBHOOK_SECRET");

  const headerPayload = headers();
  const svix_id = headerPayload.get("svix-id");
  const svix_timestamp = headerPayload.get("svix-timestamp");
  const svix_signature = headerPayload.get("svix-signature");

  const body = await req.text();
  const wh = new Webhook(WEBHOOK_SECRET);
  const evt = wh.verify(body, {
    "svix-id": svix_id!,
    "svix-timestamp": svix_timestamp!,
    "svix-signature": svix_signature!,
  }) as WebhookEvent;

  // 处理事件
  switch (evt.type) {
    case "user.created":
      // 同步到数据库
      break;
  }

  return new Response("OK", { status: 200 });
}

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

.github/workflows/validate.yml

name: Validate Clerk Config run: | python3 ~/.claude/skills/clerk-validator/scripts/validate.py
--root .
--strict
--ci

undefined

name: Validate Clerk Config run: | python3 ~/.claude/skills/clerk-validator/scripts/validate.py
--root .
--strict
--ci

undefined

Integration

集成工具

```
nextjs-validator
```
- Validates Next.js 16 (proxy.ts)
```
biome-validator
```
- Validates linting config
```
git-safety
```
- Ensures no secrets committed

```
nextjs-validator
```
- 验证Next.js 16（proxy.ts）配置
```
biome-validator
```
- 验证代码检查配置
```
git-safety
```
- 确保没有敏感信息被提交