Summary
This gives Claude the context it needs to implement Clerk authentication properly in Next.js apps, with actual code patterns instead of hand-waving. It covers the full stack: middleware setup with route matchers, server components using auth() and currentUser(), client hooks like useUser and useAuth, and critically, how to protect server actions individually. The defense-in-depth approach is good, it emphasizes validating auth at every data access point rather than trusting middleware alone. You also get role-based access patterns, organization support, and JWT handling for external APIs. If you're building anything with user accounts in Next.js, this prevents the common mistakes around assuming middleware protection is enough.
Install to Claude Code
npx -y skills add mindrally/skills --skill clerk-authentication --agent claude-codeInstalls into .claude/skills of the current project.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Files
SKILL.mdView on GitHub
Clerk Authentication
You are an expert in Clerk authentication implementation for Next.js applications. Follow these guidelines when integrating Clerk.
Core Principles
- Implement defense-in-depth with multiple authentication layers
- Verify authentication at every data access point, not just middleware
- Protect server actions individually
- Use Clerk's built-in security features (HttpOnly cookies, CSRF protection)
Installation and Setup
npm install @clerk/nextjs
Environment Variables
# 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
Provider Setup
App Router (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>
);
}
With Custom Appearance
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>
);
}
Middleware Configuration
Basic Middleware (middleware.ts)
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)(.*)',
],
};
Advanced Middleware with Role-Based Access
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();
}
});
Authentication in Server Components
Using auth()
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} />;
}
Using currentUser()
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>
);
}
Authentication in Client Components
useUser Hook
'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>
);
}
useAuth Hook
'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>;
}
Server Actions Protection
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;
}
With Role Validation
'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');
}
API Route Protection
Route Handlers (App Router)
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 });
}
JWT Verification for External APIs
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());
}
Organization Support
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 },
});
}
Custom Session Claims
Configure in Clerk Dashboard
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');
}
}
UI Components
Pre-built Components
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>
);
}
Security Best Practices
1. Defense in Depth
// 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');
// ...
}
2. Protect All Server Actions
// Every server action should verify auth independently
'use server';
export async function sensitiveAction() {
const { userId } = await auth();
if (!userId) throw new Error('Unauthorized');
// ...
}
3. Avoid Client-Side Only Protection
// 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} />;
}
Error Handling
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;
}
}
Testing
// 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);
});
});
Common Anti-Patterns to Avoid
- Relying solely on middleware for protection
- Not protecting server actions individually
- Using client-side auth checks for sensitive data
- Exposing user data without ownership verification
- Not validating organization membership for org-scoped resources
- Hardcoding role checks instead of using Clerk's RBAC
- Not handling loading states in client components
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
