clerk-auth

name	clerk-auth
description	Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync
category	Development & Code Tools
source	antigravity
tags	["typescript","react","node","nextjs","docx","xlsx","api","ai","image","vulnerability"]
url	https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/clerk-auth

Clerk Authentication

Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync

Patterns

Next.js App Router Setup

Complete Clerk setup for Next.js 14/15 App Router.

Includes ClerkProvider, environment variables, and basic sign-in/sign-up components.

Key components:

• ClerkProvider: Wraps app for auth context
• , : Pre-built auth forms
• : User menu with session management

Code_example

Environment variables (.env.local)

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... CLERK_SECRET_KEY=sk_test_... 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

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

export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); }

// app/sign-in/[[...sign-in]]/page.tsx import { SignIn } from '@clerk/nextjs';

export default function SignInPage() { return (

); }

// app/sign-up/[[...sign-up]]/page.tsx import { SignUp } from '@clerk/nextjs';

export default function SignUpPage() { return (

); }

// components/Header.tsx import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs';

export function Header() { return (

My App

); }

Anti_patterns

• Pattern: ClerkProvider inside page component | Why: Provider must wrap entire app in root layout | Fix: Move ClerkProvider to app/layout.tsx
• Pattern: Using auth() without middleware | Why: auth() requires clerkMiddleware to be configured | Fix: Set up middleware.ts with clerkMiddleware

References

• https://clerk.com/docs/nextjs/getting-started/quickstart

Middleware Route Protection

Protect routes using clerkMiddleware and createRouteMatcher.

Best practices:

• Single middleware.ts file at project root
• Use createRouteMatcher for route groups
• auth.protect() for explicit protection
• Centralize all auth logic in middleware

Code_example

// middleware.ts import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

// Define protected route patterns const isProtectedRoute = createRouteMatcher([ '/dashboard(.)', '/settings(.)', '/api/private(.*)', ]);

// Define public routes (optional, for clarity) const isPublicRoute = createRouteMatcher([ '/', '/sign-in(.)', '/sign-up(.)', '/api/webhooks(.*)', ]);

export default clerkMiddleware(async (auth, req) => { // Protect matched routes if (isProtectedRoute(req)) { await auth.protect(); } });

export const config = { matcher: [ // Match all routes except 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: Role-based protection export default clerkMiddleware(async (auth, req) => { if (isProtectedRoute(req)) { await auth.protect(); }

// Admin routes require admin role if (req.nextUrl.pathname.startsWith('/admin')) { await auth.protect({ role: 'org:admin', }); }

// Premium routes require premium permission if (req.nextUrl.pathname.startsWith('/premium')) { await auth.protect({ permission: 'org:premium:access', }); } });

Anti_patterns

• Pattern: Multiple middleware.ts files | Why: Causes conflicts and redirect loops | Fix: Use single middleware.ts with route matchers
• Pattern: Manual redirects in components | Why: Double redirects, missed routes | Fix: Handle all redirects in middleware
• Pattern: Missing matcher config | Why: Middleware won't run on all routes | Fix: Add comprehensive matcher pattern

References

• https://clerk.com/docs/reference/nextjs/clerk-middleware

Server Component Authentication

Access auth state in Server Components using auth() and currentUser().

Key functions:

• auth(): Returns userId, sessionId, orgId, claims
• currentUser(): Returns full User object
• Both require clerkMiddleware to be configured

Code_example

// app/dashboard/page.tsx (Server Component) import { auth, currentUser } from '@clerk/nextjs/server'; import { redirect } from 'next/navigation';

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

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

// Full user data (counts toward rate limits) const user = await currentUs