| 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
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
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
