playbooks

home / skills / sickn33 / antigravity-awesome-skills / clerk-auth

clerk-auth skill

/skills/clerk-auth

This skill guides implementing Clerk authentication across Next.js App Router, middleware, and server components to secure routes and streamline user sessions.

This is most likely a fork of the clerk-auth skill from xfstudio
npx playbooks add skill sickn33/antigravity-awesome-skills --skill clerk-auth

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.5 KB
---
name: clerk-auth
description: "Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync Use when: adding authentication, clerk auth, user authentication, sign in, sign up."
source: vibeship-spawner-skills (Apache 2.0)
---

# Clerk Authentication

## Patterns

### Next.js App Router Setup

Complete Clerk setup for Next.js 14/15 App Router.

Includes ClerkProvider, environment variables, and basic
sign-in/sign-up components.

Key components:
- ClerkProvider: Wraps app for auth context
- <SignIn />, <SignUp />: Pre-built auth forms
- <UserButton />: User menu with session management


### Middleware Route Protection

Protect routes using clerkMiddleware and createRouteMatcher.

Best practices:
- Single middleware.ts file at project root
- Use createRouteMatcher for route groups
- auth.protect() for explicit protection
- Centralize all auth logic in middleware


### Server Component Authentication

Access auth state in Server Components using auth() and currentUser().

Key functions:
- auth(): Returns userId, sessionId, orgId, claims
- currentUser(): Returns full User object
- Both require clerkMiddleware to be configured


## ⚠️ Sharp Edges

| Issue | Severity | Solution |
|-------|----------|----------|
| Issue | critical | See docs |
| Issue | high | See docs |
| Issue | high | See docs |
| Issue | high | See docs |
| Issue | medium | See docs |
| Issue | medium | See docs |
| Issue | medium | See docs |
| Issue | medium | See docs |

Overview

This skill collects battle-tested Clerk authentication patterns for Python and JavaScript projects, focusing on Next.js App Router, middleware route protection, server component auth, organizations, webhooks, and user sync. It bundles practical examples and recommended setups to add reliable sign-in/sign-up flows, session handling, and centralized auth logic quickly. Use it to reduce implementation errors and follow production-ready conventions.

How this skill works

The skill provides concrete patterns and code outlines for integrating Clerk into modern apps: a Next.js App Router setup with ClerkProvider and UI components, middleware examples that use createRouteMatcher and auth.protect(), and server-side helpers like auth() and currentUser() for Server Components. It also documents webhook handling, organization-aware auth flows, and approaches for syncing Clerk users with your database or services. The guidance highlights required environment variables and placement of a single middleware entry point to centralize auth enforcement.

When to use it

  • Adding authentication to a Next.js 14/15 App Router project
  • Protecting routes and APIs with centralized middleware
  • Accessing user identity in server components or API routes
  • Implementing organization-aware access control
  • Handling Clerk webhooks and syncing external user data

Best practices

  • Keep a single middleware.ts at the project root to centralize protection rules
  • Use createRouteMatcher to declare route groups and reduce duplication
  • Apply auth.protect() for explicit route-level enforcement
  • Call auth() and currentUser() only when middleware is configured to avoid inconsistent state
  • Separate webhook handlers and validate Clerk signatures before processing
  • Design user sync as idempotent jobs and reconcile by Clerk userId

Example use cases

  • Protect an /admin route group with middleware that checks org membership
  • Render currentUser() data in server components for personalized pages
  • Use SignIn/SignUp components for client-facing auth flows with ClerkProvider
  • Process account.created webhook to create or update a local user record
  • Sync pending invitations from Clerk organizations into your app's membership table

FAQ

Do auth() and currentUser() work without middleware?

No. Both functions rely on clerkMiddleware configuration to provide reliable auth state on the server.

Where should I validate webhook signatures?

Validate signatures in the dedicated webhook handler route before performing any state changes or database writes.