Clerk SDK Patterns
Overview
Common patterns and best practices for using the Clerk SDK effectively across server components, client components, API routes, and middleware.
Prerequisites
- Clerk SDK installed and configured
- Basic understanding of React/Next.js
- ClerkProvider wrapping application
Instructions
Pattern 1: Server-Side Authentication
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>
}
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>
)
}
Pattern 2: Client-Side Hooks
'use client'
import { useUser, useAuth, useClerk, useSignIn } from '@clerk/nextjs'
export function ClientAuthExample() {
const { user, isLoaded, isSignedIn } = useUser()
const { userId, getToken, signOut } = useAuth()
const { openSignIn, openUserProfile } = useClerk()
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>
<>Hello, {user.firstName}
openUserProfile()}>Profile
signOut()}>Sign Out
)
}
Pattern 3: Protected Routes with Middleware
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()
}
})
Pattern 4: Organization-Aware Queries
import { auth } from '@clerk/nextjs/server'
export async function getOrgData() {
const { userId, orgId } = await auth()
if (orgId) {
return db.items.findMany({ where: { organizationId: orgId } })
}
return db.items.findMany({ where: { ownerId: userId } })
}
Pattern 5: Custom JWT Templates for External Services
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"
}
Output
- Server and client authentication patterns ready to use
- Protected route middleware with public route exceptions
- Organization-aware data queries
- Custom JWT tokens for third-party integrations (Supabase, Hasura, etc.)
Error Handling
| 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 /> |
Examples
Server Action with Auth Check
'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 },
})
}
Resources
Next Steps
Proceed to clerk-core-workflow-a for user sign-up and sign-in flows.
