Common Clerk SDK patterns and best practices. Use when implementing authentication flows, accessing user data, or integrating Clerk SDK methods in your application. Trigger with phrases like "clerk SDK", "clerk patterns", "clerk best practices", "clerk API usage".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill clerk-sdk-patternsLoading…
Common patterns and best practices for using the Clerk SDK effectively across server components, client components, API routes, and middleware.
// Server Component — use auth() for lightweight checks
import { auth } from '@clerk/nextjs/server'
export default async function ServerPage() {
const { userId, orgId, has } = await auth()
if (!userId) return <div>Not authenticated</div>
if (!has({ permission: 'org:posts:create' })) return <div>No permission</div>
return <div>Authorized content for {userId}</div>
}
// Use currentUser() when you need full user profile data
import { currentUser } from '@clerk/nextjs/server'
export default async function ProfilePage() {
const user = await currentUser()
if (!user) return null
return (
<div>
<h1>{user.firstName} {user.lastName}</h1>
<p>{user.emailAddresses[0]?.emailAddress}</p>
<img src={user.imageUrl} alt="Avatar" />
</div>
)
}
'use client'
import { useUser, useAuth, useClerk, useSignIn } from '@clerk/nextjs'
export function ClientAuthExample() {
const { user, isLoaded, isSignedIn } = useUser() // Full user object
const { userId, getToken, signOut } = useAuth() // Auth state + token access
const { openSignIn, openUserProfile } = useClerk() // UI controls
if (!isLoaded) return <div>Loading...</div>
if (!isSignedIn) return <button onClick={() => openSignIn()}>Sign In</button>
const fetchWithAuth = async (url: string) => {
const token = await getToken()
return fetch(url, {
headers: { Authorization: `Bearer ${token}` },
})
}
return (
<div>
<p>Hello, {user.firstName}</p>
<button onClick={() => openUserProfile()}>Profile</button>
<button onClick={() => signOut()}>Sign Out</button>
</div>
)
}
// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isPublicRoute = createRouteMatcher([
'/',
'/pricing',
'/sign-in(.*)',
'/sign-up(.*)',
'/api/webhooks(.*)',
])
export default clerkMiddleware(async (auth, req) => {
if (!isPublicRoute(req)) {
await auth.protect()
}
})
// lib/db-helpers.ts
import { auth } from '@clerk/nextjs/server'
export async function getOrgData() {
const { userId, orgId } = await auth()
if (orgId) {
// Org-scoped query: return data for the active organization
return db.items.findMany({ where: { organizationId: orgId } })
}
// Personal account: return user's own data
return db.items.findMany({ where: { ownerId: userId } })
}
// Generate a Supabase-compatible JWT
import { auth } from '@clerk/nextjs/server'
import { createClient } from '@supabase/supabase-js'
export async function getSupabaseClient() {
const { getToken } = await auth()
const supabaseToken = await getToken({ template: 'supabase' })
return createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
global: {
headers: { Authorization: `Bearer ${supabaseToken}` },
},
}
)
}
Configure the JWT template in Clerk Dashboard > JWT Templates with claims:
{
"sub": "{{user.id}}",
"email": "{{user.primary_email_address}}",
"role": "authenticated"
}
| Error | Cause | Solution |
|---|---|---|
auth() returns null userId | Not in server context | Use only in Server Components or API routes |
useUser() not updating | Stale component | Check ClerkProvider wraps the component tree |
getToken() fails | JWT template not configured | Create template in Dashboard > JWT Templates |
orgId is null | No organization selected | Prompt user with <OrganizationSwitcher /> |
'use server'
import { auth } from '@clerk/nextjs/server'
export async function createPost(title: string, content: string) {
const { userId, orgId } = await auth()
if (!userId) throw new Error('Unauthorized')
return db.post.create({
data: { title, content, authorId: userId, orgId },
})
}
Proceed to clerk-core-workflow-a for user sign-up and sign-in flows.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).