clerk-nextjs-patterns

Advanced Next.js patterns for authentication, middleware, Server Actions, and user-scoped caching with Clerk.

- Distinguishes server-side await auth() from client-side useAuth() hook; mixing them is a common breaking mistake

- Covers middleware strategies (public-first vs protected-first), API route protection, and proper HTTP status codes (401 vs 403)

- Includes user-scoped caching patterns with unstable_cache and protecting Server Actions from unauthorized mutations

- Provides Core 2 compatibility notes throughout; check package.json for SDK version and follow version-specific guidance on isAuthenticated, sessionStatus, and component APIs

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.

What Do You Need?

Task
Reference

Server vs client auth (auth() vs hooks)
references/server-vs-client.md

Configure middleware (public-first vs protected-first)
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

References