Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-nextjs-patterns

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

Advanced Next.js patterns - middleware, Server Actions, caching with Clerk.

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-nextjs-patterns

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈25 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈5.9k more on demand in 8 files.

Description uses 1.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈99 characters, or 1.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Next.js Patterns

Version: Check package.json for the SDK version — see clerk skill for the version table. Core 2 differences are noted inline with > **Core 2 ONLY (skip if current SDK):** callouts.

For basic setup, see clerk-setup skill.

Route protection: call await auth.protect() in each page, Route Handler, and Server Function. Keep clerkMiddleware() bare. createRouteMatcher is deprecated in @clerk/nextjs 7 and will be removed in the next major version. Don't add it. If a project already uses it, leave it working and point the user to the migration guide.

What Do You Need?

Task Reference
Server vs client auth (auth() vs hooks) references/server-vs-client.md
Protect routes (check in each page, handler, and Server Function) references/middleware-strategies.md
Protect Server Actions references/server-actions.md
API route auth (401 vs 403) references/api-routes.md
Cache auth data (user-scoped caching) references/caching-auth.md
Fix next build errors under Cache Components Cache Components

References

Reference Description
references/server-vs-client.md await auth() vs hooks
references/middleware-strategies.md auth.protect() in each resource, bare clerkMiddleware() in proxy.ts (Next.js <=15: middleware.ts)
references/server-actions.md Protect mutations
references/api-routes.md 401 vs 403
references/caching-auth.md User-scoped caching with 'use cache'

Mental Model

Server vs Client = different auth APIs:

  • Server: await auth() from @clerk/nextjs/server (async!)
  • Client: useAuth() hook from @clerk/nextjs (sync)

Never mix them. Server Components use server imports, Client Components use hooks.

Key properties from auth():

  • isAuthenticated — boolean, replaces the !!userId pattern
  • sessionStatus — 'active' | 'pending', for detecting incomplete session tasks
  • userId, orgId, orgSlug, has(), protect() — unchanged

Core 2 ONLY (skip if current SDK): isAuthenticated and sessionStatus are not available. Check !!userId instead.

Minimal Pattern

// Server Component
import { auth } from '@clerk/nextjs/server'
import { Suspense } from 'react'

async function Greeting() {
  const { isAuthenticated, userId } = await auth() // MUST await!
  if (!isAuthenticated) return <p>Not signed in</p>
  return <p>Hello {userId}</p>
}

export default function Page() {
  return (
    <Suspense>
      <Greeting />
    </Suspense>
  )
}

auth() reads the request, so it runs in an async child inside <Suspense>, not in the page itself. See Cache Components.

Core 2 ONLY (skip if current SDK): isAuthenticated is not available. Use if (!userId) instead.

Conditional Rendering with <Show>

<Show> renders its children based on auth state. It covers both authentication checks and authorization (feature, plan, role, permission) in one component. In a Server Component, it reads the session from the request on the server, so wrap it in <Suspense>. In a Client Component, it reads client-side auth state and needs no boundary.

Authentication check:

import { Show } from '@clerk/nextjs'
import { Suspense } from 'react'

export function AuthenticatedDashboard() {
  return (
    <Suspense>
      <Show when="signed-in" fallback={<p>Please sign in</p>}>
        <Dashboard />
      </Show>
    </Suspense>
  )
}

Authorization checks (B2B) (wrap in <Suspense> the same way when rendered in a Server Component):

// Feature-based (preferred — features can move between plans without redeploy)
<Show when={{ feature: 'analytics' }} fallback={<UpgradePrompt />}>
  <AnalyticsDashboard />
</Show>

// Permission-based (preferred over role-based for granular access)
<Show when={{ permission: 'org:invoices:create' }}>
  <NewInvoiceButton />
</Show>

// Plan-based (tier-level gating)
<Show when={{ plan: 'pro' }}>
  <ProFeatures />
</Show>

// Role-based (use sparingly — prefer permission)
<Show when={{ role: 'org:admin' }}>
  <AdminPanel />
</Show>

Callback for complex logic:

<Show when={(has) => has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })}>
  <BillingActions />
</Show>

Core 2 ONLY (skip if current SDK): <Show> does not exist. For authentication, use <SignedIn> and <SignedOut>. For authorization (role / permission), use <Protect> with the same prop names (role, permission, condition). Feature- and plan-based variants require Core 3. See clerk-custom-ui skill, core-3/show-component.md for the full migration table.

Cache Components

New Next.js apps set cacheComponents: true in next.config (the create-next-app default since Next.js 16.4). With it, next build fails on request data read outside a <Suspense> boundary: Next.js encountered uncached or runtime data during prerendering. See Cache Components in Clerk's rendering modes guide.

  • Wrap <Show> rendered in a Server Component, and any Server Component that calls auth() or currentUser(), in <Suspense>, as close to the auth-dependent UI as possible. Keep <ClerkProvider> and static layout outside the boundary so Next.js can prerender them.
  • In a layout header, put one <Suspense> inside <header> around both the signed-out and signed-in <Show> blocks.
  • A page that calls auth() or currentUser() to render data: move the read into an async child inside <Suspense> and keep the default-export page synchronous.
  • A page that gates its whole render with auth.protect(), redirectToSignIn(), or redirect(): leave the page as is and add a loading.tsx next to it. See Read auth data inside Suspense.
  • Wrap catch-all <SignIn />, <SignUp />, <UserProfile />, and <OrganizationProfile /> pages in <Suspense>. They read the URL with usePathname(), even in a Client Component. See Prebuilt components on catch-all routes.
  • Never call auth() inside 'use cache'. Read the ID outside and pass it in. See references/caching-auth.md and Cache data per user with 'use cache'.

Use next build --debug-prerender to list every failing route. A plain next build stops at the first.

Common Pitfalls

Symptom Cause Fix
undefined userId in Server Component Missing await await auth() not auth()
Auth not working on API routes Missing matcher Add '/api(.*)' and '/trpc(.*)' to proxy.ts (Next.js <=15: middleware.ts)
next build fails with "uncached or runtime data during prerendering" auth(), currentUser(), or server <Show> outside <Suspense> Wrap the auth-dependent UI in <Suspense> (see Cache Components)
Cache returns wrong user's data userId not part of the cache key Pass userId into the 'use cache' function as an argument
Mutations bypass auth Unprotected Server Action Check auth() at start of action
Protected page returns 200, not 307, while signed out The redirect happened after streaming started (e.g. under a loading.tsx) Confirm the body redirects to sign-in and has no protected data. Keep the check in the page
Wrong HTTP error code Confused 401/403 401 = not signed in, 403 = no permission

Session Tokens & Custom JWTs

getToken() for external APIs

Pass a custom JWT to third-party services (Hasura, Supabase, etc.) using JWT templates defined in the Clerk dashboard.

Server-side (Server Component or Route Handler):

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

export async function ExternalData() {
  const { getToken } = await auth()
  const token = await getToken({ template: 'hasura' })
  if (!token) return <p>Not authenticated</p>

  const res = await fetch('https://api.example.com/graphql', {
    headers: { Authorization: `Bearer ${token}` },
  })
  const data = await res.json()
  return <pre>{JSON.stringify(data)}</pre>
}

Render <ExternalData /> inside <Suspense>.

Client-side (Client Component):

'use client'
import { useAuth } from '@clerk/nextjs'

export function DataFetcher() {
  const { getToken } = useAuth()

  async function fetchData() {
    const token = await getToken({ template: 'supabase' })
    if (!token) return

    const res = await fetch('https://api.example.com/data', {
      headers: { Authorization: `Bearer ${token}` },
    })
    return res.json()
  }

  return <button onClick={fetchData}>Fetch</button>
}

getToken() returns null when the user is not authenticated — always null-check before use.

useSession() for session data

Access session metadata in client components:

'use client'
import { useSession } from '@clerk/nextjs'

export function SessionInfo() {
  const { session } = useSession()
  if (!session) return null

  return (
    <p>
      Session {session.id} — last active: {session.lastActiveAt.toISOString()}
    </p>
  )
}

Manual JWT verification (no Clerk middleware)

For standalone API servers that receive Clerk session tokens from the Authorization header or the __session cookie (same-origin).

Using @clerk/backend verifyToken (recommended):

import { verifyToken } from '@clerk/backend'

const token = req.headers.authorization?.replace('Bearer ', '')
if (!token) return res.status(401).json({ error: 'No token' })

try {
  const claims = await verifyToken(token, {
    jwtKey: process.env.CLERK_JWT_KEY,
  })
  // claims.sub = userId
} catch {
  return res.status(401).json({ error: 'Invalid token' })
}

Using jsonwebtoken (when you can't use @clerk/backend):

import jwt from 'jsonwebtoken'

const publicKey = process.env.CLERK_PEM_PUBLIC_KEY!.replace(/\\n/g, '\n')
const token = req.headers.authorization?.replace('Bearer ', '')
if (!token) return res.status(401).json({ error: 'No token' })

try {
  const claims = jwt.verify(token, publicKey, { algorithms: ['RS256'] }) as jwt.JwtPayload
  // Manually check exp and nbf (jsonwebtoken does this automatically, but verify azp if needed)
  // claims.sub = userId
} catch {
  return res.status(401).json({ error: 'Invalid or expired token' })
}

Token sources:

  • Same-origin requests: __session cookie (Clerk sets this automatically)
  • Cross-origin / mobile / API-to-API: Authorization: Bearer <token> header

CRITICAL: Always check exp and nbf claims. verifyToken from @clerk/backend handles this automatically; with raw jsonwebtoken, set ignoreExpiration: false (default) and ensure clockTolerance is minimal.

See Also

  • clerk-setup - Initial Clerk install
  • clerk-orgs - B2B patterns (active org, role/permission gating)
  • clerk-billing - Plan and feature entitlements with has()
  • clerk-webhooks - Sync user/org events to your database
  • clerk-custom-ui - Theming and customization for built-in components

Docs

Next.js SDK

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts9d5 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    This skill provides secure, best-practice patterns for integrating Clerk authentication into Next.js applications, covering Server Components, API routes, and caching strategies.

  • Socket9d

    No alerts

  • Snyk10d

    Risk: LOW · No issues

  • Runlayer8mo

    7 files scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 95f241a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
What it can do
Network
metadata
{
  "author": "clerk",
  "version": "2.2.0"
}
All 1 allowed tools
WebFetch
Other metadata
compatibility
Requires NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY. For manual JWT verification (standalone API servers without Clerk middleware), additionally requires CLERK_JWT_KEY or CLERK_PEM_PUBLIC_KEY.

README badge

README badge for clerk/skills/clerk-nextjs-patterns

Provides Next.js patterns for Clerk auth using Server Components, Server Actions, middleware, and caching. Covers server vs client auth APIs (`auth()` vs hooks), protecting mutations, session tokens for external APIs, and manual JWT verification for standalone servers.

Generated from the current SKILL.md.

Does this skill require Clerk to be already set up in my Next.js project?
Yes. See the `clerk-setup` skill for initial installation. This skill covers advanced patterns — middleware, Server Actions, caching, and auth flows — assuming Clerk is already configured with NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY.
What's the difference between `auth()` and `useAuth()`?
`auth()` is a server-side async function for Server Components and Route Handlers. `useAuth()` is a client-side hook for Client Components. Never mix them — use the appropriate API for your component type.
How do I protect Server Actions from unauthorized calls?
Call `await auth()` at the start of your Server Action and check `isAuthenticated` or `userId`. If the user fails the check, throw an error or return early. The skill includes a reference guide in `references/server-actions.md`.
Does this work with Core 2 Clerk SDK?
Yes, but with differences. The skill notes Core 2 limitations inline — for example, `isAuthenticated` and `sessionStatus` don't exist in Core 2, so use `!!userId` instead. Check your `package.json` for the installed version.
Can I use this for standalone API servers without Clerk middleware?
Yes. The skill covers manual JWT verification using `@clerk/backend`'s `verifyToken` or the `jsonwebtoken` library. You'll need CLERK_JWT_KEY or CLERK_PEM_PUBLIC_KEY in addition to the standard Clerk environment variables.

Generated from the current SKILL.md. These answers refresh after source changes.