1---
2name: clerk-nextjs-patterns
3description: Advanced Next.js patterns - middleware, Server Actions, caching with
4  Clerk.
5license: MIT
6allowed-tools: WebFetch
7compatibility: 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.
8metadata:
9  author: clerk
10  version: 2.2.0
11---
12 
13# Next.js Patterns
14 
15> **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.
16 
17For basic setup, see `clerk-setup` skill.
18 
19## What Do You Need?
20 
21| Task | Reference |
22|------|-----------|
23| Server vs client auth (`auth()` vs hooks) | references/server-vs-client.md |
24| Configure middleware (public-first vs protected-first) | references/middleware-strategies.md |
25| Protect Server Actions | references/server-actions.md |
26| API route auth (401 vs 403) | references/api-routes.md |
27| Cache auth data (user-scoped caching) | references/caching-auth.md |
28 
29## References
30 
31| Reference | Description |
32|-----------|-------------|
33| `references/server-vs-client.md` | `await auth()` vs hooks |
34| `references/middleware-strategies.md` | Public-first vs protected-first, `proxy.ts` (Next.js <=15: `middleware.ts`) |
35| `references/server-actions.md` | Protect mutations |
36| `references/api-routes.md` | 401 vs 403 |
37| `references/caching-auth.md` | User-scoped caching |
38 
39## Mental Model
40 
41Server vs Client = different auth APIs:
42- **Server**: `await auth()` from `@clerk/nextjs/server` (async!)
43- **Client**: `useAuth()` hook from `@clerk/nextjs` (sync)
44 
45Never mix them. Server Components use server imports, Client Components use hooks.
46 
47Key properties from `auth()`:
48- `isAuthenticated` — boolean, replaces the `!!userId` pattern
49- `sessionStatus` — `'active'` | `'pending'`, for detecting incomplete session tasks
50- `userId`, `orgId`, `orgSlug`, `has()`, `protect()` — unchanged
51 
52> **Core 2 ONLY (skip if current SDK):** `isAuthenticated` and `sessionStatus` are not available. Check `!!userId` instead.
53 
54## Minimal Pattern
55 
56```typescript
57// Server Component
58import { auth } from '@clerk/nextjs/server'
59 
60export default async function Page() {
61  const { isAuthenticated, userId } = await auth()  // MUST await!
62  if (!isAuthenticated) return <p>Not signed in</p>
63  return <p>Hello {userId}</p>
64}
65```
66 
67> **Core 2 ONLY (skip if current SDK):** `isAuthenticated` is not available. Use `if (!userId)` instead.
68 
69### Conditional Rendering with `<Show>`
70 
71For client-side conditional rendering based on auth state. `<Show>` covers both authentication checks and authorization (feature, plan, role, permission) in one component.
72 
73**Authentication check:**
74 
75```tsx
76import { Show } from '@clerk/nextjs'
77 
78<Show when="signed-in" fallback={<p>Please sign in</p>}>
79  <Dashboard />
80</Show>
81```
82 
83**Authorization checks (B2B):**
84 
85```tsx
86// Feature-based (preferred — features can move between plans without redeploy)
87<Show when={{ feature: 'analytics' }} fallback={<UpgradePrompt />}>
88  <AnalyticsDashboard />
89</Show>
90 
91// Permission-based (preferred over role-based for granular access)
92<Show when={{ permission: 'org:invoices:create' }}>
93  <NewInvoiceButton />
94</Show>
95 
96// Plan-based (tier-level gating)
97<Show when={{ plan: 'pro' }}>
98  <ProFeatures />
99</Show>
100 
101// Role-based (use sparingly — prefer permission)
102<Show when={{ role: 'org:admin' }}>
103  <AdminPanel />
104</Show>
105```
106 
107**Callback for complex logic:**
108 
109```tsx
110<Show when={(has) => has({ role: 'org:admin' }) || has({ role: 'org:billing_manager' })}>
111  <BillingActions />
112</Show>
113```
114 
115> **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.
116 
117## Common Pitfalls
118 
119| Symptom | Cause | Fix |
120|---------|-------|-----|
121| `undefined` userId in Server Component | Missing `await` | `await auth()` not `auth()` |
122| Auth not working on API routes | Missing matcher | Add `'/(api|trpc)(.*)'` to `proxy.ts` (Next.js <=15: `middleware.ts`) |
123| Cache returns wrong user's data | Missing userId in key | Include `userId` in `unstable_cache` key |
124| Mutations bypass auth | Unprotected Server Action | Check `auth()` at start of action |
125| Wrong HTTP error code | Confused 401/403 | 401 = not signed in, 403 = no permission |
126 
127## Session Tokens & Custom JWTs
128 
129### getToken() for external APIs
130 
131Pass a custom JWT to third-party services (Hasura, Supabase, etc.) using JWT templates defined in the Clerk dashboard.
132 
133**Server-side (Server Component or Route Handler)**:
134 
135```typescript
136import { auth } from '@clerk/nextjs/server'
137 
138export default async function Page() {
139  const { getToken } = await auth()
140  const token = await getToken({ template: 'hasura' })
141  if (!token) return <p>Not authenticated</p>
142 
143  const res = await fetch('https://api.example.com/graphql', {
144    headers: { Authorization: `Bearer ${token}` },
145  })
146  const data = await res.json()
147  return <pre>{JSON.stringify(data)}</pre>
148}
149```
150 
151**Client-side (Client Component)**:
152 
153```typescript
154'use client'
155import { useAuth } from '@clerk/nextjs'
156 
157export function DataFetcher() {
158  const { getToken } = useAuth()
159 
160  async function fetchData() {
161    const token = await getToken({ template: 'supabase' })
162    if (!token) return
163 
164    const res = await fetch('https://api.example.com/data', {
165      headers: { Authorization: `Bearer ${token}` },
166    })
167    return res.json()
168  }
169 
170  return <button onClick={fetchData}>Fetch</button>
171}
172```
173 
174`getToken()` returns `null` when the user is not authenticated — always null-check before use.
175 
176### useSession() for session data
177 
178Access session metadata in client components:
179 
180```typescript
181'use client'
182import { useSession } from '@clerk/nextjs'
183 
184export function SessionInfo() {
185  const { session } = useSession()
186  if (!session) return null
187 
188  return (
189    <p>
190      Session {session.id} — last active: {session.lastActiveAt.toISOString()}
191    </p>
192  )
193}
194```
195 
196### Manual JWT verification (no Clerk middleware)
197 
198For standalone API servers that receive Clerk session tokens from the `Authorization` header or the `__session` cookie (same-origin).
199 
200**Using `@clerk/backend` `verifyToken`** (recommended):
201 
202```typescript
203import { verifyToken } from '@clerk/backend'
204 
205const token = req.headers.authorization?.replace('Bearer ', '')
206if (!token) return res.status(401).json({ error: 'No token' })
207 
208try {
209  const claims = await verifyToken(token, {
210    jwtKey: process.env.CLERK_JWT_KEY,
211  })
212  // claims.sub = userId
213} catch {
214  return res.status(401).json({ error: 'Invalid token' })
215}
216```
217 
218**Using `jsonwebtoken`** (when you can't use `@clerk/backend`):
219 
220```typescript
221import jwt from 'jsonwebtoken'
222 
223const publicKey = process.env.CLERK_PEM_PUBLIC_KEY!.replace(/\\n/g, '\n')
224const token = req.headers.authorization?.replace('Bearer ', '')
225if (!token) return res.status(401).json({ error: 'No token' })
226 
227try {
228  const claims = jwt.verify(token, publicKey, { algorithms: ['RS256'] }) as jwt.JwtPayload
229  // Manually check exp and nbf (jsonwebtoken does this automatically, but verify azp if needed)
230  // claims.sub = userId
231} catch {
232  return res.status(401).json({ error: 'Invalid or expired token' })
233}
234```
235 
236Token sources:
237- **Same-origin requests**: `__session` cookie (Clerk sets this automatically)
238- **Cross-origin / mobile / API-to-API**: `Authorization: Bearer <token>` header
239 
240> **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.
241 
242## See Also
243 
244- `clerk-setup` - Initial Clerk install
245- `clerk-orgs` - B2B patterns (active org, role/permission gating)
246- `clerk-billing` - Plan and feature entitlements with `has()`
247- `clerk-webhooks` - Sync user/org events to your database
248- `clerk-custom-ui` - Theming and customization for built-in components
249 
250## Docs
251 
252[Next.js SDK](https://clerk.com/docs/reference/nextjs/overview)
253