| name | nextjs-clerk |
| description | Help write Next.js applications with Clerk authentication. Use when the user asks about adding Clerk auth to a Next.js app, protecting routes, using authentication hooks, implementing sign-in/sign-up flows, or working with organizations in Next.js. |
| license | MIT |
| metadata | {"author":"clerk","version":"1.0.0"} |
Next.js Clerk Authentication Skill
This skill helps you implement Clerk authentication in Next.js applications. It covers the App Router (Next.js 15+), server components, client components, proxy middleware, and common authentication patterns.
Note: Next.js 16+ uses proxy.ts instead of middleware.ts. For Next.js 15 or earlier, use middleware.ts with the same code.
Quick Start
1. Install Dependencies
npm install @clerk/nextjs
2. Set Environment Variables
Create a .env.local file with your Clerk keys from the Clerk Dashboard:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx
3. Wrap Your App with ClerkProvider
import { ClerkProvider } from '@clerk/nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
);
}
4. Add Proxy Middleware for Route Protection
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)']);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
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)(.*)',
],
};
Available Scripts
This skill provides shell scripts to scaffold common Clerk patterns:
| Script | Description |
|---|
bash scripts/setup.sh | Set up a new Next.js project with Clerk |
bash scripts/middleware.sh | Generate middleware with route protection |
bash scripts/auth-pages.sh | Generate sign-in and sign-up pages |
bash scripts/components.sh | Generate common auth component patterns |
bash scripts/webhook.sh | Generate webhook handler for Clerk events |
Common Patterns
Server Components (Recommended)
Access auth state in Server Components:
import { auth, currentUser } from '@clerk/nextjs/server';
export default async function DashboardPage() {
const { userId, orgId } = await auth();
if (!userId) {
return <div>Please sign in</div>;
}
const user = await currentUser();
return <h1>Welcome, {user?.firstName}!</h1>;
}
Client Components
Use hooks in Client Components:
'use client';
import { useUser, useAuth } from '@clerk/nextjs';
export function UserGreeting() {
const { isLoaded, isSignedIn, user } = useUser();
const { getToken } = useAuth();
if (!isLoaded) return <div>Loading...</div>;
if (!isSignedIn) return <div>Not signed in</div>;
return <p>Hello, {user.firstName}!</p>;
}
API Routes
Protect API routes:
import { auth } from '@clerk/nextjs/server';
export async function GET() {
const { userId } = await auth();
if (!userId) {
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
return Response.json({ data: 'Protected data' });
}
Pre-built Components
Use Clerk's pre-built UI components:
import {
SignIn,
SignUp,
UserButton,
SignedIn,
SignedOut,
SignInButton,
SignUpButton,
} from '@clerk/nextjs';
<SignedIn>
<UserButton />
</SignedIn>
<SignedOut>
<SignInButton />
</SignedOut>
Organizations (B2B)
For multi-tenant applications with organizations:
Enable Organizations
- Go to Clerk Dashboard → Organizations → Settings
- Enable Organizations
Use Organization Hooks
'use client';
import { useOrganization, useOrganizationList } from '@clerk/nextjs';
export function OrgDashboard() {
const { organization, membership } = useOrganization();
const { setActive } = useOrganizationList();
return (
<div>
<h1>{organization?.name}</h1>
<p>Your role: {membership?.role}</p>
</div>
);
}
Protect Routes by Organization
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isOrgRoute = createRouteMatcher(['/dashboard(.*)']);
export default clerkMiddleware(async (auth, req) => {
const { orgId } = await auth();
if (isOrgRoute(req) && !orgId) {
return Response.redirect(new URL('/select-org', req.url));
}
});
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)(.*)',
],
};
Webhooks
Handle Clerk webhook events:
import { Webhook } from 'svix';
import { headers } from 'next/headers';
import { WebhookEvent } from '@clerk/nextjs/server';
export async function POST(req: Request) {
const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET!;
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');
const payload = await req.json();
const body = JSON.stringify(payload);
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) {
return Response.json({ error: 'Invalid webhook' }, { status: 400 });
}
switch (evt.type) {
case 'user.created':
break;
case 'organization.created':
break;
}
return Response.json({ received: true });
}
Documentation
