Agent Skills
› fanfan-de/anybox
› auth
auth
GitHub提供Next.js应用的身份验证集成指南，涵盖Clerk、Descope和Auth0。包含中间件配置、路由保护、用户数据获取及登录注册流程实现，特别推荐Clerk的Vercel原生集成方案。
Trigger Scenarios
需要为Next.js应用添加用户认证功能
询问如何集成Clerk、Descope或Auth0
配置身份验证中间件或受保护路由
Install
npx skills add fanfan-de/anybox --skill auth -g -y
SKILL.md
Frontmatter
{
"name": "auth",
"chainTo": [
{
"message": "Auth logic in middleware.ts — loading Routing Middleware guidance for proxy.ts migration in Next.js 16.",
"pattern": "export\\s+(default\\s+)?function\\s+middleware",
"targetSkill": "routing-middleware"
},
{
"message": "Manual JWT handling with jsonwebtoken detected — use Clerk or Auth.js for managed auth with built-in JWT session handling, CSRF protection, and token rotation.",
"pattern": "from\\s+['\\\"](jsonwebtoken)['\"]|require\\s*\\(\\s*['\\\"](jsonwebtoken)['\"]|jwt\\.sign\\s*\\(",
"targetSkill": "auth"
},
{
"message": "Legacy next-auth (v4) pattern detected — loading auth guidance for Auth.js v5 migration with the new universal auth() helper.",
"pattern": "from\\s+['\\\"](next-auth)['\"]|NextAuthOptions|authOptions\\s*:",
"targetSkill": "auth"
},
{
"message": "Clerk import detected — loading Auth guidance for Clerk v7 patterns, middleware setup, organization handling, and Vercel Marketplace integration.",
"pattern": "from\\s+['\"]@clerk\/nextjs['\"]",
"targetSkill": "auth",
"skipIfFileContains": "clerkMiddleware|ClerkProvider"
},
{
"message": "Manual password hashing detected (bcrypt\/argon2) — use Clerk or Auth0 for managed authentication with built-in password hashing, rate limiting, and breach detection.",
"pattern": "bcrypt|argon2",
"targetSkill": "auth",
"skipIfFileContains": "@clerk|@auth0"
}
],
"metadata": {
"docs": [
"https:\/\/authjs.dev\/getting-started",
"https:\/\/nextjs.org\/docs\/app\/building-your-application\/authentication"
],
"sitemap": "https:\/\/authjs.dev\/sitemap.xml",
"priority": 6,
"bashPatterns": [
"\\bnpm\\s+(install|i|add)\\s+[^\\n]*@clerk\/nextjs\\b",
"\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@clerk\/nextjs\\b",
"\\bbun\\s+(install|i|add)\\s+[^\\n]*@clerk\/nextjs\\b",
"\\byarn\\s+add\\s+[^\\n]*@clerk\/nextjs\\b",
"\\bnpm\\s+(install|i|add)\\s+[^\\n]*@descope\/nextjs-sdk\\b",
"\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@descope\/nextjs-sdk\\b",
"\\bbun\\s+(install|i|add)\\s+[^\\n]*@descope\/nextjs-sdk\\b",
"\\byarn\\s+add\\s+[^\\n]*@descope\/nextjs-sdk\\b",
"\\bnpm\\s+(install|i|add)\\s+[^\\n]*@auth0\/nextjs-auth0\\b",
"\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@auth0\/nextjs-auth0\\b",
"\\bbun\\s+(install|i|add)\\s+[^\\n]*@auth0\/nextjs-auth0\\b",
"\\byarn\\s+add\\s+[^\\n]*@auth0\/nextjs-auth0\\b"
],
"pathPatterns": [
"middleware.ts",
"middleware.js",
"src\/middleware.ts",
"src\/middleware.js",
"clerk.config.*",
"app\/sign-in\/**",
"app\/sign-up\/**",
"src\/app\/sign-in\/**",
"src\/app\/sign-up\/**",
"app\/(auth)\/**",
"src\/app\/(auth)\/**",
"auth.config.*",
"auth.ts",
"auth.js"
]
},
"validate": [
{
"message": "Hand-rolled Vercel OAuth detected. Use the Sign in with Vercel OIDC provider instead of manual token exchange.",
"pattern": "VERCEL_CLIENT_(ID|SECRET)|vercel\\.com\/oauth\/(authorize|access_token|token)",
"severity": "recommended",
"skipIfFileContains": "signInWithVercel|@vercel\/auth"
}
],
"retrieval": {
"aliases": [
"authentication",
"login system",
"sign in",
"auth flow"
],
"intents": [
"add auth",
"protect routes",
"manage sessions",
"implement login",
"secure api endpoints"
],
"entities": [
"NextAuth",
"Auth.js",
"JWT",
"OAuth",
"session",
"middleware",
"getServerSession"
],
"examples": [
"add login to my app",
"protect this route with auth",
"set up NextAuth"
]
},
"description": "Authentication integration guidance — Clerk (native Vercel Marketplace), Descope, and Auth0 setup for Next.js applications. Covers middleware auth patterns, sign-in\/sign-up flows, and Marketplace provisioning. Use when implementing user authentication."
}
Authentication Integrations
You are an expert in authentication for Vercel-deployed applications — covering Clerk (native Vercel Marketplace integration), Descope, and Auth0.
Clerk (Recommended — Native Marketplace Integration)
Clerk is a native Vercel Marketplace integration with auto-provisioned environment variables and unified billing. Current SDK: @clerk/nextjs v7 (Core 3, March 2026).
Install via Marketplace
# Install Clerk from Vercel Marketplace (auto-provisions env vars)
vercel integration add clerk
Auto-provisioned environment variables:
CLERK_SECRET_KEY— server-side API keyNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY— client-side publishable key
SDK Setup
# Install the Clerk Next.js SDK
npm install @clerk/nextjs
Middleware Configuration
// middleware.ts
import { clerkMiddleware } from "@clerk/nextjs/server";
export default clerkMiddleware();
export const config = {
matcher: [
// Skip Next.js internals and static files
"/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
// Always run for API routes
"/(api|trpc)(.*)",
],
};
Protect Routes
// middleware.ts — protect specific routes
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";
const isProtectedRoute = createRouteMatcher(["/dashboard(.*)", "/api(.*)"]);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
Frontend API Proxy (Core 3)
Proxy Clerk's Frontend API through your own domain to avoid third-party requests:
// middleware.ts
export default clerkMiddleware({
frontendApiProxy: { enabled: true },
});
Provider Setup
// app/layout.tsx
import { ClerkProvider } from "@clerk/nextjs";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<ClerkProvider>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
);
}
Sign-In and Sign-Up Pages
// app/sign-in/[[...sign-in]]/page.tsx
import { SignIn } from "@clerk/nextjs";
export default function Page() {
return <SignIn />;
}
// app/sign-up/[[...sign-up]]/page.tsx
import { SignUp } from "@clerk/nextjs";
export default function Page() {
return <SignUp />;
}
Add routing env vars to .env.local:
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
Access User Data
// Server component
import { currentUser } from "@clerk/nextjs/server";
export default async function Page() {
const user = await currentUser();
return <p>Hello, {user?.firstName}</p>;
}
// Client component
"use client";
import { useUser } from "@clerk/nextjs";
export default function UserGreeting() {
const { user, isLoaded } = useUser();
if (!isLoaded) return null;
return <p>Hello, {user?.firstName}</p>;
}
API Route Protection
// app/api/protected/route.ts
import { auth } from "@clerk/nextjs/server";
export async function GET() {
const { userId } = await auth();
if (!userId) {
return Response.json({ error: "Unauthorized" }, { status: 401 });
}
return Response.json({ userId });
}
Descope
Descope is available on the Vercel Marketplace with native integration support.
Install via Marketplace
vercel integration add descope
SDK Setup
npm install @descope/nextjs-sdk
Provider and Middleware
// app/layout.tsx
import { AuthProvider } from "@descope/nextjs-sdk";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<AuthProvider projectId={process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID!}>
<html lang="en">
<body>{children}</body>
</html>
</AuthProvider>
);
}
// middleware.ts
import { authMiddleware } from "@descope/nextjs-sdk/server";
export default authMiddleware({
projectId: process.env.DESCOPE_PROJECT_ID!,
publicRoutes: ["/", "/sign-in"],
});
Sign-In Flow
"use client";
import { Descope } from "@descope/nextjs-sdk";
export default function SignInPage() {
return <Descope flowId="sign-up-or-in" />;
}
Auth0
Auth0 provides a mature authentication platform with extensive identity provider support.
SDK Setup
npm install @auth0/nextjs-auth0
Configuration
// lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";
export const auth0 = new Auth0Client();
Required environment variables:
AUTH0_SECRET=<random-secret>
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=<client-id>
AUTH0_CLIENT_SECRET=<client-secret>
Middleware
// middleware.ts
import { auth0 } from "@/lib/auth0";
import { NextRequest, NextResponse } from "next/server";
export async function middleware(request: NextRequest) {
return await auth0.middleware(request);
}
export const config = {
matcher: [
"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
],
};
Access Session Data
// Server component
import { auth0 } from "@/lib/auth0";
export default async function Page() {
const session = await auth0.getSession();
return session ? (
<p>Hello, {session.user.name}</p>
) : (
<a href="/auth/login">Log in</a>
);
}
Decision Matrix
| Need | Recommended | Why |
|---|---|---|
| Fastest setup on Vercel | Clerk | Native Marketplace, auto-provisioned env vars |
| Passwordless / social login flows | Descope | Visual flow builder, Marketplace native |
| Enterprise SSO / SAML / multi-tenant | Auth0 | Deep enterprise identity support |
| Pre-built UI components | Clerk | Drop-in <SignIn />, <UserButton /> |
| Vercel unified billing | Clerk or Descope | Both are native Marketplace integrations |
Clerk Core 3 Breaking Changes (March 2026)
Clerk provides an upgrade CLI that scans your codebase and applies codemods: npx @clerk/upgrade. Requires Node.js 20.9.0+.
auth()is async — always useconst { userId } = await auth(), not synchronousauth.protect()moved — useawait auth.protect()directly, not from the return value ofauth()clerkClient()is async — useawait clerkClient()in middleware handlersauthMiddleware()removed — migrate toclerkMiddleware()@clerk/typesdeprecated — import types from SDK subpath exports:import type { UserResource } from '@clerk/react/types'(works from any SDK package)ClerkProviderno longer forces dynamic rendering — pass thedynamicprop if needed- Cache components — when using Next.js cache components, place
<ClerkProvider>inside<body>, not wrapping<html> - Satellite domains — new
satelliteAutoSyncoption skips handshake redirects when no session cookies exist - Smaller bundles — React is now shared across framework SDKs (~50KB gzipped savings)
- Better offline handling —
getToken()now correctly distinguishes signed-out from offline states
Cross-References
- Marketplace install and env var provisioning →
⤳ skill: marketplace - Middleware routing patterns →
⤳ skill: routing-middleware - Environment variable management →
⤳ skill: env-vars
Official Documentation
Version History
- 08dc189 Current 2026-07-05 19:11
