clerk-sdk-patterns

# 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
```typescript
// 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>
}
```

```typescript
// 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>
  )
}
```

### Pattern 2: Client-Side Hooks
```typescript
'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>
  )
}
```

### Pattern 3: Protected Routes with Middleware
```typescript
// 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()
  }
})
```

### Pattern 4: Organization-Aware Queries
```typescript
// 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 } })
}
```

### Pattern 5: Custom JWT Templates for External Services
```typescript
// 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:
```json
{
  "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
```typescript
'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
- [Clerk SDK Reference](https://clerk.com/docs/references/nextjs/overview)
- [Auth Helper](https://clerk.com/docs/references/nextjs/auth)
- [JWT Templates](https://clerk.com/docs/backend-requests/making/jwt-templates)

## Next Steps
Proceed to `clerk-core-workflow-a` for user sign-up and sign-in flows.