Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync Use when: adding authentication, clerk auth, user authentication, sign in, sign up.
npxskills add sickn33/antigravity-awesome-skills--skill clerk-authLoading…
Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync
Complete Clerk setup for Next.js 14/15 App Router.
Includes ClerkProvider, environment variables, and basic sign-in/sign-up components.
Key components:
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 ( <ClerkProvider> <html lang="en"> <body>{children}</body> </html> </ClerkProvider> ); }
// app/sign-in/[[...sign-in]]/page.tsx import { SignIn } from '@clerk/nextjs';
export default function SignInPage() { return ( <div className="flex justify-center items-center min-h-screen"> <SignIn /> </div> ); }
// app/sign-up/[[...sign-up]]/page.tsx import { SignUp } from '@clerk/nextjs';
export default function SignUpPage() { return ( <div className="flex justify-center items-center min-h-screen"> <SignUp /> </div> ); }
// components/Header.tsx import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs';
export function Header() { return ( <header className="flex justify-between p-4"> <h1>My App</h1> <SignedOut> <SignInButton /> </SignedOut> <SignedIn> <UserButton afterSignOutUrl="/" /> </SignedIn> </header> ); }
Protect routes using clerkMiddleware and createRouteMatcher.
Best practices:
// 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', }); } });
Access auth state in Server Components using auth() and currentUser().
Key functions:
// 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 currentUser();
return ( <div> <h1>Welcome, {user?.firstName}!</h1> <p>Email: {user?.emailAddresses[0]?.emailAddress}</p> </div> ); }
// Using auth() for quick checks export default async function ProtectedLayout({ children, }: { children: React.ReactNode; }) { const { userId, orgId, orgRole } = await auth();
if (!userId) { redirect('/sign-in'); }
// Check organization access if (!orgId) { redirect('/select-org'); }
return ( <div> <p>Organization Role: {orgRole}</p> {children} </div> ); }
// Server Action with auth check // app/actions/posts.ts '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;
// Create post with userId const post = await prisma.post.create({ data: { title, authorId: userId, }, });
return post; }
Access auth state in Client Components using hooks.
Key hooks:
// components/UserProfile.tsx 'use client'; import { useUser, useAuth } from '@clerk/nextjs';
export function UserProfile() { const { user, isLoaded, isSignedIn } = useUser(); const { signOut } = useAuth();
if (!isLoaded) { return <div>Loading...</div>; }
if (!isSignedIn) { return <div>Not signed in</div>; }
return ( <div> <img src={user.imageUrl} alt={user.fullName ?? ''} /> <h2>{user.fullName}</h2> <p>{user.emailAddresses[0]?.emailAddress}</p> <button onClick={() => signOut()}>Sign Out</button> </div> ); }
// Organization context 'use client'; import { useOrganization, useOrganizationList } from '@clerk/nextjs';
export function OrgSwitcher() { const { organization, membership } = useOrganization(); const { setActive, userMemberships } = useOrganizationList({ userMemberships: { infinite: true }, });
if (!organization) { return <p>No organization selected</p>; }
return ( <div> <p>Current: {organization.name}</p> <p>Role: {membership?.role}</p>
<select
onChange={(e) => setActive?.({ organization: e.target.value })}
value={organization.id}
>
{userMemberships.data?.map((mem) => (
<option key={mem.organization.id} value={mem.organization.id}>
{mem.organization.name}
</option>
))}
</select>
</div>
); }
// Protected client component 'use client'; import { useAuth } from '@clerk/nextjs'; import { useRouter } from 'next/navigation'; import { useEffect } from 'react';
export function ProtectedContent() { const { isLoaded, userId } = useAuth(); const router = useRouter();
useEffect(() => { if (isLoaded && !userId) { router.push('/sign-in'); } }, [isLoaded, userId, router]);
if (!isLoaded || !userId) { return <div>Loading...</div>; }
return <div>Protected content here</div>; }
Implement B2B multi-tenancy with Clerk Organizations.
Features:
// Organization creation UI // app/create-org/page.tsx import { CreateOrganization } from '@clerk/nextjs';
export default function CreateOrgPage() { return ( <div className="flex justify-center"> <CreateOrganization afterCreateOrganizationUrl="/dashboard" /> </div> ); }
// Organization profile and management // app/org-settings/page.tsx import { OrganizationProfile } from '@clerk/nextjs';
export default function OrgSettingsPage() { return <OrganizationProfile />; }
// Organization switcher in header // components/Header.tsx import { OrganizationSwitcher, UserButton } from '@clerk/nextjs';
export function Header() { return ( <header className="flex justify-between p-4"> <OrganizationSwitcher hidePersonal afterCreateOrganizationUrl="/dashboard" afterSelectOrganizationUrl="/dashboard" /> <UserButton /> </header> ); }
// Org-scoped data access // app/dashboard/page.tsx import { auth } from '@clerk/nextjs/server'; import { prisma } from '@/lib/prisma';
export default async function DashboardPage() { const { orgId } = await auth();
if (!orgId) { redirect('/select-org'); }
// Fetch org-scoped data const projects = await prisma.project.findMany({ where: { organizationId: orgId }, });
return ( <div> <h1>Projects</h1> {projects.map((p) => ( <div key={p.id}>{p.name}</div> ))} </div> ); }
// Role-based UI 'use client'; import { useOrganization, Protect } from '@clerk/nextjs';
export function AdminPanel() { const { membership } = useOrganization();
// Using Protect component return ( <Protect role="org:admin" fallback={<p>Admin access required</p>}> <div>Admin content here</div> </Protect> );
// Or manual check if (membership?.role !== 'org:admin') { return <p>Admin access required</p>; }
return <div>Admin content here</div>; }
Sync Clerk users to your database using webhooks.
Key webhooks:
Uses svix for signature verification.
// app/api/webhooks/clerk/route.ts import { Webhook } from 'svix'; import { headers } from 'next/headers'; import { WebhookEvent } from '@clerk/nextjs/server'; import { prisma } from '@/lib/prisma';
export async function POST(req: Request) { const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;
if (!WEBHOOK_SECRET) { throw new Error('Missing CLERK_WEBHOOK_SECRET'); }
// Get headers const headerPayload = await headers(); const svix_id = headerPayload.get('svix-id'); const svix_timestamp = headerPayload.get('svix-timestamp'); const svix_signature = headerPayload.get('svix-signature');
if (!svix_id || !svix_timestamp || !svix_signature) { return new Response('Missing svix headers', { status: 400 }); }
// Get body const payload = await req.json(); const body = JSON.stringify(payload);
// Verify webhook const wh = new Webhook(WEBHOOK_SECRET); let evt: WebhookEvent;
try { evt = wh.verify(body, { 'svix-id': svix_id, 'svix-timestamp': svix_timestamp, 'svix-signature': svix_signature, }) as WebhookEvent; } catch (err) { console.error('Webhook verification failed:', err); return new Response('Verification failed', { status: 400 }); }
// Handle events const eventType = evt.type;
if (eventType === 'user.created') { const { id, email_addresses, first_name, last_name, image_url } = evt.data;
await prisma.user.create({
data: {
clerkId: id,
email: email_addresses[0]?.email_address,
firstName: first_name,
lastName: last_name,
imageUrl: image_url,
},
});
}
if (eventType === 'user.updated') { const { id, email_addresses, first_name, last_name, image_url } = evt.data;
await prisma.user.update({
where: { clerkId: id },
data: {
email: email_addresses[0]?.email_address,
firstName: first_name,
lastName: last_name,
imageUrl: image_url,
},
});
}
if (eventType === 'user.deleted') { const { id } = evt.data;
await prisma.user.delete({
where: { clerkId: id! },
});
}
return new Response('Webhook processed', { status: 200 }); }
// Prisma schema // prisma/schema.prisma model User { id String @id @default(cuid()) clerkId String @unique email String @unique firstName String? lastName String? imageUrl String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt
posts Post[] @@index([clerkId]) }
Protect API routes using auth() from Clerk.
Route Handlers in App Router use auth() for authentication. Middleware provides initial protection, auth() provides in-handler verification.
// app/api/projects/route.ts import { auth } from '@clerk/nextjs/server'; import { prisma } from '@/lib/prisma'; import { NextResponse } from 'next/server';
export async function GET() { const { userId, orgId } = await auth();
if (!userId) { return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }); }
// User's personal projects or org projects const projects = await prisma.project.findMany({ where: orgId ? { organizationId: orgId } : { userId, organizationId: null }, });
return NextResponse.json(projects); }
export async function POST(req: Request) { const { userId, orgId } = await auth();
if (!userId) { return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }); }
const body = await req.json();
const project = await prisma.project.create({ data: { name: body.name, userId, organizationId: orgId ?? null, }, });
return NextResponse.json(project, { status: 201 }); }
// Protected with role check // app/api/admin/users/route.ts export async function GET() { const { userId, orgRole } = await auth();
if (!userId) { return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }); }
if (orgRole !== 'org:admin') { return NextResponse.json({ error: 'Forbidden' }, { status: 403 }); }
// Admin-only logic const users = await prisma.user.findMany(); return NextResponse.json(users); }
// Using getAuth in older patterns (not recommended) // For backwards compatibility only import { getAuth } from '@clerk/nextjs/server';
export async function GET(req: Request) { const { userId } = getAuth(req); // ... }
Severity: CRITICAL
Severity: HIGH
Severity: HIGH
Severity: HIGH
Severity: MEDIUM
Severity: MEDIUM
Severity: MEDIUM
Severity: MEDIUM
Severity: MEDIUM
Severity: HIGH
Severity: ERROR
CLERK_SECRET_KEY must only be used server-side
Message: Clerk secret key exposed to client. Use CLERK_SECRET_KEY without NEXT_PUBLIC prefix.
Severity: ERROR
API routes should have middleware protection
Message: API route without auth check. Add middleware protection or auth() check.
Severity: ERROR
Clerk keys should use environment variables
Message: Hardcoded Clerk keys. Use environment variables.
Severity: ERROR
auth() is async in App Router and must be awaited
Message: auth() not awaited. Use 'await auth()' in App Router.
Severity: WARNING
Only one middleware.ts file should exist
Message: Multiple middleware files detected. Use single middleware.ts.
Severity: WARNING
Webhook routes should be public
Message: Webhook route may be blocked by middleware. Add to public routes.
Severity: WARNING
Check isLoaded before accessing user state in client components
Message: Accessing user without isLoaded check. Check isLoaded first.
Severity: ERROR
Clerk hooks only work in Client Components
Message: Clerk hooks in Server Component. Add 'use client' or use auth().
Severity: WARNING
Organization data should be scoped by orgId
Message: Query without organization scope. Filter by orgId for multi-tenancy.
Severity: ERROR
Clerk webhooks must verify svix signature
Message: Webhook without signature verification. Use svix to verify.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).