clerk-nextjs-patterns
Installation
Summary
Advanced Next.js patterns for authentication, middleware, Server Actions, and user-scoped caching with Clerk.
- Distinguishes server-side
await auth()from client-sideuseAuth()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_cacheand protecting Server Actions from unauthorized mutations - Provides Core 2 compatibility notes throughout; check
package.jsonfor SDK version and follow version-specific guidance onisAuthenticated,sessionStatus, and component APIs
SKILL.md
Next.js Patterns
Version: Check
package.jsonfor the SDK version — seeclerkskill 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. KeepclerkMiddleware()bare.createRouteMatcheris deprecated in@clerk/nextjs7 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 |