clerk-nextjs-skills_skill

Overview

This skill integrates Clerk authentication into Next.js 16 (App Router) projects and documents the proxy.ts migration from middleware.ts. It includes proxy.ts setup, environment variable validation, route protection patterns, and optional MCP server integration for AI tooling. The content focuses on practical steps to get Clerk running with Prisma ORM and AI SDK workflows.

How this skill works

It installs @clerk/nextjs and configures clerkMiddleware via proxy.ts (root or /src) for Next.js 16. The middleware matcher controls which routes Clerk processes and can call auth.protect() to require authentication. Client and server patterns show how to use ClerkProvider, useUser hooks, server-side auth(), and clerkClient() for secure user data access. MCP server integration uses @vercel/mcp-adapter and @clerk/mcp-tools with token verification and .well-known endpoints.

When to use it

• Upgrading a Next.js 15 app using middleware.ts to Next.js 16 (App Router).
• Adding user sign-in, sign-up, and session management to a Next.js 16 app.
• Exposing machine-capable endpoints for AI agents via an MCP server.
• Protecting API and app routes while keeping static assets public.
• Integrating Clerk with Prisma ORM and AI SDK workflows.

Best practices

• Place proxy.ts at project root or /src; keep middleware code identical when migrating.
• Store sensitive keys in .env.local for development and set platform env vars for production.
• Validate required environment variables at startup and fail fast if missing.
• Use auth.protect() only for routes that require authentication; use createRouteMatcher to scope protection.
• Use clerkClient() in server code and Clerk hooks only inside 'use client' components.
• Expose .well-known MCP endpoints as public, but verify OAuth tokens with verifyClerkToken() before returning user data.

Example use cases

• Quickstart: install @clerk/nextjs, add proxy.ts, wrap app/layout with ClerkProvider, and start dev server.
• Protect a dashboard route with createRouteMatcher and auth.protect() in proxy.ts.
• Build an MCP handler that returns Clerk user data after verifying machine OAuth tokens.
• Server action that calls clerkClient() to fetch and return secure profile data for the signed-in user.
• Migrate an existing middleware.ts to proxy.ts without changing middleware logic.