# Clerk Auth
> Implements Clerk on Next.js App Router: ClerkProvider, clerkMiddleware/auth.protect(), organizations, Svix user-sync webhooks, and server auth()/client hooks. Use when the user mentions Clerk, ClerkProvider, sign-in/sign-up, organizations, SSO, or Clerk webhooks on Next.js 14/15. Not for Auth.js, NextAuth, Firebase Auth, or Clerk on non-Next stacks. Never trust middleware alone (CVE-2025-29927); re-check auth() in the handler.
- Skill: `kayforkind/clerk-auth` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kayforkind/clerk-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kayforkind/clerk-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Kayforkind (https://skillmd.com/u/kayforkind)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/kayforkind/clerk-auth
---
# Clerk Authentication
Expert patterns for Clerk auth implementation in Next.js 14/15 App Router: provider setup, middleware route protection, server/client component auth, organizations, webhook user sync, and API route protection.
## When to Use
Activate this skill when the user mentions or implies any of:
- Adding authentication to a Next.js app
- Clerk auth, ClerkProvider, or Clerk components
- User authentication, sign-in, sign-up flows
- User management or session handling
- Multi-tenancy or Clerk Organizations
- SSO / single sign-on
- Webhook-based user sync to a database
- Route protection via middleware
## Prerequisites
- Next.js 14 or 15 with App Router enabled
- A Clerk application created at clerk.com (publishable key + secret key)
- `@clerk/nextjs` installed: `npm install @clerk/nextjs`
- `svix` installed if using webhooks: `npm install svix`
- Environment variables configured in `.env.local` (never commit real keys)
## Procedure
### 1. Configure Environment Variables
Create `.env.local` with Clerk keys. The secret key must **never** have the `NEXT_PUBLIC_` prefix.
```bash
# .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_YOUR_KEY
CLERK_SECRET_KEY=sk_test_YOUR_KEY
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
```
### 2. Wrap the App with ClerkProvider
`ClerkProvider` must live in the root layout — never inside a page component.
```tsx
// app/layout.tsx
import { ClerkProvider } from '@clerk/nextjs';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
### 3. Add Sign-In and Sign-Up Pages
Use Clerk's pre-built components with catch-all routes.
```tsx
// app/sign-in/[[...sign-in]]/page.tsx
import { SignIn } from '@clerk/nextjs';
export default function SignInPage() {
return (
);
}
```
```tsx
// app/sign-up/[[...sign-up]]/page.tsx
import { SignUp } from '@clerk/nextjs';
export default function SignUpPage() {
return (
);
}
```
### 4. Add a Header with Auth Controls
```tsx
// components/Header.tsx
import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs';
export function Header() {
return (
My App
);
}
```
### 5. Set Up Middleware Route Protection
Place a **single** `middleware.ts` at the project root. Use `createRouteMatcher` for route groups and `auth.protect()` for explicit protection.
```ts
// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isProtectedRoute = createRouteMatcher([
'/dashboard(.*)',
'/settings(.*)',
'/api/private(.*)',
]);
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/webhooks(.*)',
]);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
// Role-based protection
if (req.nextUrl.pathname.startsWith('/admin')) {
await auth.protect({ role: 'org:admin' });
}
// Permission-based protection
if (req.nextUrl.pathname.startsWith('/premium')) {
await auth.protect({ permission: 'org:premium:access' });
}
});
export const config = {
matcher: [
'/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
'/(api|trpc)(.*)',
],
};
```
### 6. Access Auth in Server Components
Use `auth()` for quick checks (userId, orgId, orgRole). Use `currentUser()` only when you need the full User object — it counts toward rate limits.
```tsx
// app/dashboard/page.tsx
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');
}
const user = await currentUser();
return (
Welcome, {user?.firstName}!
Email: {user?.emailAddresses[0]?.emailAddress}
);
}
```
Server Actions also use `auth()`:
```ts
// 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;
const post = await prisma.post.create({
data: { title, authorId: userId },
});
return post;
}
```
### 7. Access Auth in Client Components
Always check `isLoaded` before reading user/auth state.
```tsx
// 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