clerk-authentication by mindrally/skills
npx skills add https://github.com/mindrally/skills --skill clerk-authentication您是 Next.js 应用程序中 Clerk 身份验证实现的专家。在集成 Clerk 时请遵循以下指南。
npm install @clerk/nextjs
# 必需
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
# 可选:自定义 URL
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=/dashboard
import { ClerkProvider } from '@clerk/nextjs';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<ClerkProvider>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
);
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
import { ClerkProvider } from '@clerk/nextjs';
import { dark } from '@clerk/themes';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider
appearance={{
baseTheme: dark,
variables: {
colorPrimary: '#3b82f6',
},
elements: {
formButtonPrimary: 'bg-blue-500 hover:bg-blue-600',
},
}}
>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
);
}
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
// 定义受保护路由
const isProtectedRoute = createRouteMatcher([
'/dashboard(.*)',
'/api/protected(.*)',
'/settings(.*)',
]);
// 定义公共路由(可选,为了清晰)
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/public(.*)',
]);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
export const config = {
matcher: [
// 跳过 Next.js 内部文件和静态文件
'/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
// 始终为 API 路由运行
'/(api|trpc)(.*)',
],
};
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isAdminRoute = createRouteMatcher(['/admin(.*)']);
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/protected(.*)']);
export default clerkMiddleware(async (auth, req) => {
const { userId, sessionClaims } = await auth();
// 管理员路由需要 admin 角色
if (isAdminRoute(req)) {
if (!userId || sessionClaims?.metadata?.role !== 'admin') {
return new Response('Forbidden', { status: 403 });
}
}
// 受保护路由需要身份验证
if (isProtectedRoute(req)) {
await auth.protect();
}
});
import { auth } from '@clerk/nextjs/server';
export default async function DashboardPage() {
const { userId } = await auth();
if (!userId) {
redirect('/sign-in');
}
// 获取用户特定数据
const data = await fetchUserData(userId);
return <Dashboard data={data} />;
}
import { currentUser } from '@clerk/nextjs/server';
export default async function ProfilePage() {
const user = await currentUser();
if (!user) {
redirect('/sign-in');
}
return (
<div>
<h1>欢迎, {user.firstName}!</h1>
<p>邮箱: {user.emailAddresses[0]?.emailAddress}</p>
</div>
);
}
'use client';
import { useUser } from '@clerk/nextjs';
export function UserProfile() {
const { isLoaded, isSignedIn, user } = useUser();
if (!isLoaded) {
return <Skeleton />;
}
if (!isSignedIn) {
return <SignInPrompt />;
}
return (
<div>
<img src={user.imageUrl} alt={user.fullName ?? 'User'} />
<p>{user.fullName}</p>
</div>
);
}
'use client';
import { useAuth } from '@clerk/nextjs';
export function ProtectedAction() {
const { isLoaded, userId, getToken } = useAuth();
async function handleAction() {
if (!userId) return;
// 为 API 调用获取新令牌
const token = await getToken();
const response = await fetch('/api/protected', {
headers: {
Authorization: `Bearer ${token}`,
},
});
}
if (!isLoaded || !userId) {
return null;
}
return <button onClick={handleAction}>执行操作</button>;
}
始终单独保护服务器操作:
'use server';
import { auth } from '@clerk/nextjs/server';
export async function createPost(formData: FormData) {
const { userId } = await auth();
if (!userId) {
throw new Error('未授权');
}
const title = formData.get('title') as string;
const content = formData.get('content') as string;
// 使用用户 ID 创建帖子
const post = await db.post.create({
data: {
title,
content,
authorId: userId,
},
});
revalidatePath('/posts');
return post;
}
'use server';
import { auth } from '@clerk/nextjs/server';
export async function deleteUser(userId: string) {
const { userId: currentUserId, sessionClaims } = await auth();
if (!currentUserId) {
throw new Error('未授权');
}
if (sessionClaims?.metadata?.role !== 'admin') {
throw new Error('禁止访问:需要管理员权限');
}
await db.user.delete({ where: { id: userId } });
revalidatePath('/admin/users');
}
import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';
export async function GET() {
const { userId } = await auth();
if (!userId) {
return NextResponse.json({ error: '未授权' }, { status: 401 });
}
const data = await fetchUserData(userId);
return NextResponse.json(data);
}
export async function POST(request: Request) {
const { userId } = await auth();
if (!userId) {
return NextResponse.json({ error: '未授权' }, { status: 401 });
}
const body = await request.json();
// 处理请求...
return NextResponse.json({ success: true });
}
import { auth } from '@clerk/nextjs/server';
export async function GET() {
const { getToken } = await auth();
// 获取用于外部 API 的 JWT
const token = await getToken({ template: 'external-api' });
const response = await fetch('https://external-api.com/data', {
headers: {
Authorization: `Bearer ${token}`,
},
});
return Response.json(await response.json());
}
import { auth } from '@clerk/nextjs/server';
export async function getOrganizationData() {
const { userId, orgId, orgRole } = await auth();
if (!userId || !orgId) {
throw new Error('必须在组织中');
}
// 检查组织角色
if (orgRole !== 'org:admin') {
throw new Error('需要管理员权限');
}
return await db.organization.findUnique({
where: { clerkOrgId: orgId },
});
}
通过 JWT 模板添加自定义声明,然后访问它们:
import { auth } from '@clerk/nextjs/server';
export async function checkSubscription() {
const { sessionClaims } = await auth();
const plan = sessionClaims?.metadata?.subscriptionPlan;
if (plan !== 'pro') {
throw new Error('需要专业版订阅');
}
}
import {
SignIn,
SignUp,
SignOutButton,
UserButton,
SignedIn,
SignedOut,
} from '@clerk/nextjs';
export function Header() {
return (
<header>
<SignedIn>
<UserButton afterSignOutUrl="/" />
</SignedIn>
<SignedOut>
<SignInButton mode="modal" />
</SignedOut>
</header>
);
}
// 专用登录页面
export default function SignInPage() {
return (
<div className="flex justify-center items-center min-h-screen">
<SignIn />
</div>
);
}
// 第 1 层:中间件
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
// 第 2 层:服务器组件
export default async function Page() {
const { userId } = await auth();
if (!userId) redirect('/sign-in');
// ...
}
// 第 3 层:数据访问
async function fetchUserData(userId: string) {
const { userId: currentUserId } = await auth();
if (currentUserId !== userId) throw new Error('禁止访问');
// ...
}
// 每个服务器操作都应独立验证身份验证
'use server';
export async function sensitiveAction() {
const { userId } = await auth();
if (!userId) throw new Error('未授权');
// ...
}
// 错误:仅客户端检查
'use client';
export function SecretComponent() {
const { isSignedIn } = useAuth();
if (!isSignedIn) return null;
return <div>秘密数据</div>; // 数据仍会发送到客户端!
}
// 正确:服务器端保护
export default async function SecretPage() {
const { userId } = await auth();
if (!userId) redirect('/sign-in');
const data = await fetchSecretData(userId);
return <SecretComponent data={data} />;
}
import { auth } from '@clerk/nextjs/server';
import { redirect } from 'next/navigation';
export default async function ProtectedPage() {
try {
const { userId } = await auth();
if (!userId) {
redirect('/sign-in');
}
const data = await fetchUserData(userId);
return <Dashboard data={data} />;
} catch (error) {
if (error instanceof AuthenticationError) {
redirect('/sign-in');
}
throw error;
}
}
// 模拟 Clerk 进行测试
import { auth } from '@clerk/nextjs/server';
jest.mock('@clerk/nextjs/server', () => ({
auth: jest.fn(),
}));
describe('受保护的 API', () => {
it('对未认证的请求返回 401', async () => {
(auth as jest.Mock).mockResolvedValue({ userId: null });
const response = await GET();
expect(response.status).toBe(401);
});
it('对已认证的请求返回数据', async () => {
(auth as jest.Mock).mockResolvedValue({ userId: 'user_123' });
const response = await GET();
expect(response.status).toBe(200);
});
});
每周安装量
93
仓库
GitHub 星标数
44
首次出现
2026 年 1 月 25 日
安全审计
安装于
gemini-cli78
opencode77
cursor74
claude-code73
codex73
github-copilot70
You are an expert in Clerk authentication implementation for Next.js applications. Follow these guidelines when integrating Clerk.
npm install @clerk/nextjs
# Required
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
# Optional: Custom URLs
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=/dashboard
import { ClerkProvider } from '@clerk/nextjs';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<ClerkProvider>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
);
}
import { ClerkProvider } from '@clerk/nextjs';
import { dark } from '@clerk/themes';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider
appearance={{
baseTheme: dark,
variables: {
colorPrimary: '#3b82f6',
},
elements: {
formButtonPrimary: 'bg-blue-500 hover:bg-blue-600',
},
}}
>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
);
}
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
// Define protected routes
const isProtectedRoute = createRouteMatcher([
'/dashboard(.*)',
'/api/protected(.*)',
'/settings(.*)',
]);
// Define public routes (optional, for clarity)
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/public(.*)',
]);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
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)(.*)',
],
};
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isAdminRoute = createRouteMatcher(['/admin(.*)']);
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/protected(.*)']);
export default clerkMiddleware(async (auth, req) => {
const { userId, sessionClaims } = await auth();
// Admin routes require admin role
if (isAdminRoute(req)) {
if (!userId || sessionClaims?.metadata?.role !== 'admin') {
return new Response('Forbidden', { status: 403 });
}
}
// Protected routes require authentication
if (isProtectedRoute(req)) {
await auth.protect();
}
});
import { auth } from '@clerk/nextjs/server';
export default async function DashboardPage() {
const { userId } = await auth();
if (!userId) {
redirect('/sign-in');
}
// Fetch user-specific data
const data = await fetchUserData(userId);
return <Dashboard data={data} />;
}
import { currentUser } from '@clerk/nextjs/server';
export default async function ProfilePage() {
const user = await currentUser();
if (!user) {
redirect('/sign-in');
}
return (
<div>
<h1>Welcome, {user.firstName}!</h1>
<p>Email: {user.emailAddresses[0]?.emailAddress}</p>
</div>
);
}
'use client';
import { useUser } from '@clerk/nextjs';
export function UserProfile() {
const { isLoaded, isSignedIn, user } = useUser();
if (!isLoaded) {
return <Skeleton />;
}
if (!isSignedIn) {
return <SignInPrompt />;
}
return (
<div>
<img src={user.imageUrl} alt={user.fullName ?? 'User'} />
<p>{user.fullName}</p>
</div>
);
}
'use client';
import { useAuth } from '@clerk/nextjs';
export function ProtectedAction() {
const { isLoaded, userId, getToken } = useAuth();
async function handleAction() {
if (!userId) return;
// Get a fresh token for API calls
const token = await getToken();
const response = await fetch('/api/protected', {
headers: {
Authorization: `Bearer ${token}`,
},
});
}
if (!isLoaded || !userId) {
return null;
}
return <button onClick={handleAction}>Perform Action</button>;
}
Always protect server actions individually:
'use server';
import { auth } from '@clerk/nextjs/server';
export async function createPost(formData: FormData) {
const { userId } = await auth();
if (!userId) {
throw new Error('Unauthorized');
}
const title = formData.get('title') as string;
const content = formData.get('content') as string;
// Create post with user ID
const post = await db.post.create({
data: {
title,
content,
authorId: userId,
},
});
revalidatePath('/posts');
return post;
}
'use server';
import { auth } from '@clerk/nextjs/server';
export async function deleteUser(userId: string) {
const { userId: currentUserId, sessionClaims } = await auth();
if (!currentUserId) {
throw new Error('Unauthorized');
}
if (sessionClaims?.metadata?.role !== 'admin') {
throw new Error('Forbidden: Admin access required');
}
await db.user.delete({ where: { id: userId } });
revalidatePath('/admin/users');
}
import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';
export async function GET() {
const { userId } = await auth();
if (!userId) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
const data = await fetchUserData(userId);
return NextResponse.json(data);
}
export async function POST(request: Request) {
const { userId } = await auth();
if (!userId) {
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}
const body = await request.json();
// Process request...
return NextResponse.json({ success: true });
}
import { auth } from '@clerk/nextjs/server';
export async function GET() {
const { getToken } = await auth();
// Get JWT for external API
const token = await getToken({ template: 'external-api' });
const response = await fetch('https://external-api.com/data', {
headers: {
Authorization: `Bearer ${token}`,
},
});
return Response.json(await response.json());
}
import { auth } from '@clerk/nextjs/server';
export async function getOrganizationData() {
const { userId, orgId, orgRole } = await auth();
if (!userId || !orgId) {
throw new Error('Must be in an organization');
}
// Check organization role
if (orgRole !== 'org:admin') {
throw new Error('Admin access required');
}
return await db.organization.findUnique({
where: { clerkOrgId: orgId },
});
}
Add custom claims via JWT Templates, then access them:
import { auth } from '@clerk/nextjs/server';
export async function checkSubscription() {
const { sessionClaims } = await auth();
const plan = sessionClaims?.metadata?.subscriptionPlan;
if (plan !== 'pro') {
throw new Error('Pro subscription required');
}
}
import {
SignIn,
SignUp,
SignOutButton,
UserButton,
SignedIn,
SignedOut,
} from '@clerk/nextjs';
export function Header() {
return (
<header>
<SignedIn>
<UserButton afterSignOutUrl="/" />
</SignedIn>
<SignedOut>
<SignInButton mode="modal" />
</SignedOut>
</header>
);
}
// Dedicated sign-in page
export default function SignInPage() {
return (
<div className="flex justify-center items-center min-h-screen">
<SignIn />
</div>
);
}
// Layer 1: Middleware
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
// Layer 2: Server Component
export default async function Page() {
const { userId } = await auth();
if (!userId) redirect('/sign-in');
// ...
}
// Layer 3: Data Access
async function fetchUserData(userId: string) {
const { userId: currentUserId } = await auth();
if (currentUserId !== userId) throw new Error('Forbidden');
// ...
}
// Every server action should verify auth independently
'use server';
export async function sensitiveAction() {
const { userId } = await auth();
if (!userId) throw new Error('Unauthorized');
// ...
}
// BAD: Client-side only check
'use client';
export function SecretComponent() {
const { isSignedIn } = useAuth();
if (!isSignedIn) return null;
return <div>Secret Data</div>; // Data still sent to client!
}
// GOOD: Server-side protection
export default async function SecretPage() {
const { userId } = await auth();
if (!userId) redirect('/sign-in');
const data = await fetchSecretData(userId);
return <SecretComponent data={data} />;
}
import { auth } from '@clerk/nextjs/server';
import { redirect } from 'next/navigation';
export default async function ProtectedPage() {
try {
const { userId } = await auth();
if (!userId) {
redirect('/sign-in');
}
const data = await fetchUserData(userId);
return <Dashboard data={data} />;
} catch (error) {
if (error instanceof AuthenticationError) {
redirect('/sign-in');
}
throw error;
}
}
// Mock Clerk for testing
import { auth } from '@clerk/nextjs/server';
jest.mock('@clerk/nextjs/server', () => ({
auth: jest.fn(),
}));
describe('Protected API', () => {
it('returns 401 for unauthenticated requests', async () => {
(auth as jest.Mock).mockResolvedValue({ userId: null });
const response = await GET();
expect(response.status).toBe(401);
});
it('returns data for authenticated requests', async () => {
(auth as jest.Mock).mockResolvedValue({ userId: 'user_123' });
const response = await GET();
expect(response.status).toBe(200);
});
});
Weekly Installs
93
Repository
GitHub Stars
44
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli78
opencode77
cursor74
claude-code73
codex73
github-copilot70
Azure RBAC 权限管理工具:查找最小角色、创建自定义角色与自动化分配
131,500 周安装