---
id: sm-clerk-nextjs-patterns
name: "clerk-nextjs-patterns"
url: https://skills.yangsir.net/skill/sm-clerk-nextjs-patterns
author: clerk
domain: ai-frontend-engineering
tags: ["clerk-auth", "nextjs", "authentication", "frontend-development", "user-management"]
install_count: 12400
rating: 4.50 (32 reviews)
github: https://github.com/clerk/skills
---

# clerk-nextjs-patterns

> 专注于Clerk与Next.js集成模式，利用AI技能增强开发效率，简化用户认证与管理流程。

**Stats**: 12,400 installs · 4.5/5 (32 reviews)

## Before / After 对比

### Next.js认证集成效率与安全性

| Metric | Before | After | Change |
|---|---|---|---|
| - | - | - | - |
| - | - | - | - |

## Readme

# clerk-nextjs-patterns

# 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 `setup/`.

## Impact Levels

- **CRITICAL** - Breaking bugs, security holes

- **HIGH** - Common mistakes

- **MEDIUM** - Optimization

## References

Reference
Impact

`references/server-vs-client.md`
CRITICAL - `await auth()` vs hooks

`references/middleware-strategies.md`
HIGH - Public-first vs protected-first, `proxy.ts` (Next.js <=15: `middleware.ts`)

`references/server-actions.md`
HIGH - Protect mutations

`references/api-routes.md`
HIGH - 401 vs 403

`references/caching-auth.md`
MEDIUM - User-scoped caching

## 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'

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

```

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

### Conditional Rendering with `<Show>`

For client-side conditional rendering based on auth state:

```
import { Show } from '@clerk/nextjs'

<Show when="signed-in" fallback={<p>Please sign in</p>}>
  <Dashboard />
</Show>

```

**Core 2 ONLY (skip if current SDK):** Use `<SignedIn>` and `<SignedOut>` components instead of `<Show>`. See `custom-ui/core-3/show-component.md` for the full migration table.

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

Cache returns wrong user's data
Missing userId in key
Include `userId` in `unstable_cache` key

Mutations bypass auth
Unprotected Server Action
Check `auth()` at start of action

Wrong HTTP error code
Confused 401/403
401 = not signed in, 403 = no permission

## See Also

- `setup/`

- `orgs/`

## Docs

[Next.js SDK](https://clerk.com/docs/reference/nextjs/overview)
Weekly Installs4.3KRepository[clerk/skills](https://github.com/clerk/skills)GitHub Stars27First SeenJan 30, 2026Security Audits[Gen Agent Trust HubPass](/clerk/skills/clerk-nextjs-patterns/security/agent-trust-hub)[SocketPass](/clerk/skills/clerk-nextjs-patterns/security/socket)[SnykPass](/clerk/skills/clerk-nextjs-patterns/security/snyk)Installed oncursor3.8Kcodex2.2Kopencode2.2Kgithub-copilot2.2Kgemini-cli2.2Kamp2.1K

---
*Source: https://skills.yangsir.net/skill/sm-clerk-nextjs-patterns*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-clerk-nextjs-patterns/markdown*