Name: Clerk Nextjs Skills
Author: nayan-dey

搵技能.../

Clerk Nextjs Skills | Skills Pool

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

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

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=/

// 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>
  )
}

pnpm dev

// 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>
}

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

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

// 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(', ')}`)
  }
}

// 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>
  )
}

// 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
}

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
```

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

// 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()
  }
})

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`

// 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)
  }
})

DEBUG_CLERK=1 pnpm dev

Clerk Nextjs Skills

Links

Clerk Nextjs Skills

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

Resources

1password

Springboot Security

Security Review

Laravel Security

Security Review

Django Security

Clerk Nextjs Skills

Links

Clerk Nextjs Skills

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

1password

Springboot Security

Security Review

Laravel Security

Security Review

Django Security