Agent skill

clerk-nextjs-skills

Quellcode ansehen: gocallum/nextjs16-agent-skills

#201Globales Ranking · von 201 SkillsMedium

Installation

npx skills add gocallum/nextjs16-agent-skills --skill clerk-nextjs-skills

411

Installationen

EU-hosted inference API

Power your AI agent skills with open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

MiniMax

MiniMax M3

$0.40 / $1.40

per M tokens

Z.ai

GLM 5.3 Flash

$0.20 / $0.60

per M tokens

MoonshotAI

Kimi K3

$4.00 / $18.00

per M tokens

DeepSeek

DeepSeek V4.1 Flash

$0.40 / $1.40

per M tokens

Quick Start

1. Install Dependencies (Using pnpm)

pnpm add @clerk/nextjs
# For MCP server integration, also install:
pnpm add @vercel/mcp-adapter @clerk/mcp-tools

2. Create proxy.ts (Next.js 16)

The proxy.ts file replaces middleware.ts from Next.js 15. Create it at the root or in /src:

// proxy.ts (or src/proxy.ts)
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware()

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)(.*)',
  ],
}

3. Set Environment Variables

Create .env.local in your project root:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key_here
CLERK_SECRET_KEY=your_secret_key_here
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

4. Add ClerkProvider to Layout

// app/layout.tsx
import {
  ClerkProvider,
  SignInButton,
  SignUpButton,
  SignedIn,
  SignedOut,
  UserButton,
} from '@clerk/nextjs'
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My App',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>
          <header className="flex justify-end items-center p-4 gap-4 h-16">
            <SignedOut>
              <SignInButton />
              <SignUpButton />
            </SignedOut>
            <SignedIn>
              <UserButton />
            </SignedIn>
          </header>
          {children}
        </body>
      </html>
    </ClerkProvider>
  )
}

5. Run Your App

pnpm dev

Visit http://localhost:3000 and click "Sign Up" to create your first user.

Key Concepts

proxy.ts vs middleware.ts

Next.js 16 (App Router): Use proxy.ts for Clerk middleware
Next.js ≤15: Use middleware.ts with identical code (filename only differs)
Clerk's clerkMiddleware() function is the same regardless of filename
The matcher configuration ensures proper route handling and performance

Protecting Routes

By default, clerkMiddleware() does not protect routes—all are public. Use auth.protect() to require authentication:

// Protect specific route
import { auth } from '@clerk/nextjs/server'

export default async function Page() {
  const { userId } = await auth()
  
  if (!userId) {
    // Redirect handled by clerkMiddleware
  }
  
  return <div>Protected content for {userId}</div>
}

Or protect all routes in proxy.ts:

import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware(async (auth, req) => {
  await auth.protect()
})

Environment Variable Validation

Check for required Clerk keys before runtime:

// lib/clerk-config.ts
export function validateClerkEnv() {
  const required = [
    'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
    'CLERK_SECRET_KEY',
  ]
  
  const missing = required.filter(key => !process.env[key])
  
  if (missing.length > 0) {
    throw new Error(`Missing required Clerk environment variables: ${missing.join(', ')}`)
  }
}

Accessing User Data

Use Clerk hooks in client components:

// app/components/user-profile.tsx
'use client'

import { useUser } from '@clerk/nextjs'

export function UserProfile() {
  const { user, isLoaded } = useUser()
  
  if (!isLoaded) return <div>Loading...</div>
  
  if (!user) return <div>Not signed in</div>
  
  return (
    <div>
      <h1>{user.fullName}</h1>
      <p>{user.primaryEmailAddress?.emailAddress}</p>
    </div>
  )
}

Or in server components/actions:

// app/actions.ts
'use server'

import { auth, clerkClient } from '@clerk/nextjs/server'

export async function getUserData() {
  const { userId } = await auth()
  
  if (!userId) {
    throw new Error('Unauthorized')
  }
  
  const clerk = await clerkClient()
  const user = await clerk.users.getUser(userId)
  
  return user
}

Migrating from middleware.ts (Next.js 15) to proxy.ts (Next.js 16)

Step-by-Step Migration

Rename the file from middleware.ts to proxy.ts (location remains same: root or /src)

Keep the code identical - No functional changes needed:

// Before (middleware.ts)
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = { ... }

// After (proxy.ts) - Same code
import { clerkMiddleware } from '@clerk/nextjs/server'
export default clerkMiddleware()
export const config = { ... }

Update Next.js version:
```
pnpm add next@latest
```
Verify environment variables are still in .env.local (no changes needed)
Test the migration:
```
pnpm dev
```

Troubleshooting Migration

If routes aren't protected, ensure proxy.ts is in the correct location (root or /src)
Check that .env.local has all required Clerk keys
Clear .next cache if middleware changes don't take effect: rm -rf .next && pnpm dev
Verify Next.js version is 16.0+: pnpm list next

Building an MCP Server with Clerk

See CLERK_MCP_SERVER_SETUP.md for complete MCP server integration.

Quick MCP Setup Summary

Install MCP dependencies:

pnpm add @vercel/mcp-adapter @clerk/mcp-tools

Create MCP route at app/[transport]/route.ts:

import { verifyClerkToken } from '@clerk/mcp-tools/next'
import { createMcpHandler, withMcpAuth } from '@vercel/mcp-adapter'
import { auth, clerkClient } from '@clerk/nextjs/server'

const clerk = await clerkClient()

const handler = createMcpHandler((server) => {
  server.tool(
    'get-clerk-user-data',
    'Gets data about the Clerk user that authorized this request',
    {},
    async (_, { authInfo }) => {
      const userId = authInfo!.extra!.userId! as string
      const userData = await clerk.users.getUser(userId)
      return {
        content: [{ type: 'text', text: JSON.stringify(userData) }],
      }
    },
  )
})

const authHandler = withMcpAuth(
  handler,
  async (_, token) => {
    const clerkAuth = await auth({ acceptsToken: 'oauth_token' })
    return verifyClerkToken(clerkAuth, token)
  },
  {
    required: true,
    resourceMetadataPath: '/.well-known/oauth-protected-resource/mcp',
  },
)

export { authHandler as GET, authHandler as POST }

Expose OAuth metadata endpoints (see references for complete setup)

Update proxy.ts to exclude .well-known endpoints:

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher([
  '/.well-known/oauth-authorization-server(.*)',
  '/.well-known/oauth-protected-resource(.*)',
])

export default clerkMiddleware(async (auth, req) => {
  if (isPublicRoute(req)) return
  await auth.protect()
})

Enable Dynamic Client Registration in Clerk Dashboard

Best Practices

1. Environment Variable Management

Always use .env.local for development (never commit sensitive keys)
Validate environment variables on application startup
Use NEXT_PUBLIC_ prefix ONLY for non-sensitive keys that are safe to expose
For production, set environment variables in your deployment platform (Vercel, etc.)

2. Route Protection Strategies

// Option A: Protect all routes
export default clerkMiddleware(async (auth, req) => {
  await auth.protect()
})

// Option B: Protect specific routes
import { createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/api/user(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) {
    await auth.protect()
  }
})

// Option C: Public routes with opt-in protection
const isPublicRoute = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) {
    await auth.protect()
  }
})

3. MCP Server Security

Enable Dynamic Client Registration in Clerk Dashboard
Keep .well-known endpoints public but protect all MCP tools with OAuth
Use acceptsToken: 'oauth_token' in auth() to require machine tokens
OAuth tokens are free during public beta (pricing TBD)
Always verify tokens with verifyClerkToken() before exposing user data

4. Performance & Caching

Use clerkClient() for server-side user queries (cached automatically)
Leverage React Server Components for secure user data access
Cache user data when possible to reduce API calls
Use @clerk/nextjs hooks only in Client Components ('use client')

5. Production Deployment

Set all environment variables in your deployment platform
Use Clerk's production instance keys (not development keys)
Test authentication flow in staging environment before production
Monitor Clerk Dashboard for authentication errors
Keep @clerk/nextjs updated: pnpm update @clerk/nextjs

Troubleshooting

Issues & Solutions

Issue	Solution
"Missing environment variables"	Ensure `.env.local` has `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`
Middleware not protecting routes	Verify `proxy.ts` is in root or `/src` directory, not in `app/`
Sign-in/sign-up pages not working	Check `NEXT_PUBLIC_CLERK_SIGN_IN_URL` and `NEXT_PUBLIC_CLERK_SIGN_UP_URL` in `.env.local`
User data returns null	Ensure user is authenticated: check `userId` is not null before calling `getUser()`
MCP server OAuth fails	Enable Dynamic Client Registration in Clerk Dashboard OAuth Applications
Changes not taking effect	Clear `.next` cache: `rm -rf .next` and restart `pnpm dev`
"proxy.ts" not recognized	Verify Next.js version is 16.0+: `pnpm list next`

Common Next.js 16 Gotchas

File naming: Must be proxy.ts (not middleware.ts) for Next.js 16
Location: Place proxy.ts at project root or in /src directory, NOT in app/
Re-exports: Config object must be exported from proxy.ts for matcher to work
Async operations: clerkMiddleware() is async-ready; use await auth.protect() for route protection

Debug Mode

Enable debug logging:

// proxy.ts
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware((auth, req) => {
  if (process.env.DEBUG_CLERK) {
    console.log('Request URL:', req.nextUrl.pathname)
    console.log('User ID:', auth.sessionClaims?.sub)
  }
})

Run with debug:

DEBUG_CLERK=1 pnpm dev

Related Skills

mcp-server-skills: General MCP server patterns with Vercel adapter
nextjs16-skills: Next.js 16 features, breaking changes, and best practices
authjs-skills: Alternative authentication using Auth.js (Auth0, GitHub, etc.)

Resources

Installationen

Installationen411

Globales Ranking#201 von 201

Sicherheitsprüfung

athSafe

socketSafe

Warnungen: 0Bewertung: 90

snykMedium

zeroleaksSafe

Bewertung: 93

Quellcode ansehen

gocallum/nextjs16-agent-skills

Mehr aus dieser Quelle

WEB DATA FOR AGENTS

Give agents clean web context

Search and extract the public web as Markdown or structured JSON through one API or hosted MCP server.

Explore Webstractor

So verwenden Sie diesen Skill

Install clerk-nextjs-skills by running npx skills add gocallum/nextjs16-agent-skills --skill clerk-nextjs-skills in your project directory. Führen Sie den obigen Installationsbefehl in Ihrem Projektverzeichnis aus. Die Skill-Datei wird von GitHub heruntergeladen und in Ihrem Projekt platziert.

Keine Konfiguration erforderlich. Ihr KI-Agent (Claude Code, Cursor, Windsurf usw.) erkennt installierte Skills automatisch und nutzt sie als Kontext bei der Code-Generierung.

Der Skill verbessert das Verständnis Ihres Agenten für clerk-nextjs-skills, und hilft ihm, etablierte Muster zu befolgen, häufige Fehler zu vermeiden und produktionsreifen Code zu erzeugen.

Was Sie erhalten

Skills sind Klartext-Anweisungsdateien — kein ausführbarer Code. Sie kodieren Expertenwissen über Frameworks, Sprachen oder Tools, das Ihr KI-Agent liest, um seine Ausgabe zu verbessern. Das bedeutet null Laufzeit-Overhead, keine Abhängigkeitskonflikte und volle Transparenz: Sie können jede Anweisung vor der Installation lesen und prüfen.

Kompatibilität

Dieser Skill funktioniert mit jedem KI-Coding-Agenten, der das skills.sh-Format unterstützt, einschließlich Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider und anderen Tools, die projektbezogene Kontextdateien lesen. Skills sind auf Transportebene framework-agnostisch — der Inhalt bestimmt, für welche Sprache oder welches Framework er gilt.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.

clerk-nextjs-skills

Power your AI agent skills with open-source models.

Links

Quick Start

1. Install Dependencies (Using pnpm)

2. Create proxy.ts (Next.js 16)

3. Set Environment Variables

4. Add ClerkProvider to Layout

5. Run Your App

Key Concepts

proxy.ts vs middleware.ts

Protecting Routes

Environment Variable Validation

Accessing User Data

Migrating from middleware.ts (Next.js 15) to proxy.ts (Next.js 16)

Step-by-Step Migration

Troubleshooting Migration

Building an MCP Server with Clerk

Quick MCP Setup Summary

Best Practices

1. Environment Variable Management

2. Route Protection Strategies

3. MCP Server Security

4. Performance & Caching

5. Production Deployment

Troubleshooting

Issues & Solutions

Common Next.js 16 Gotchas

Debug Mode

Related Skills

Resources

Installationen

Sicherheitsprüfung

Quellcode ansehen

Give agents clean web context

Verwandte Skills

prisma-orm-v7-skills

authjs-skills

nextjs16-skills

ai-sdk-6-skills

resend-integration-skills

mcp-server-skills

So verwenden Sie diesen Skill

Was Sie erhalten

Kompatibilität