clerk-upgrade-migration

# Clerk Upgrade & Migration

## Overview
Safely upgrade Clerk SDK versions and handle breaking changes.

## Prerequisites
- Current Clerk integration working
- Git repository with clean working state
- Test environment available

## Instructions

### Step 1: Check Current Version and Available Updates
```bash
# Check current version
npm list @clerk/nextjs

# Check for updates
npm outdated @clerk/nextjs

# View changelog
npm view @clerk/nextjs versions --json | tail -20
```

### Step 2: Review Breaking Changes
```typescript
// Common breaking changes by major version:

// v5 -> v6 Changes:
// - clerkMiddleware() replaces authMiddleware()
// - auth() is now async
// - Removed deprecated hooks
// - New createRouteMatcher() API

// Before (v5)
import { authMiddleware } from '@clerk/nextjs'
export default authMiddleware({
  publicRoutes: ['/']
})

// After (v6)
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isPublicRoute = createRouteMatcher(['/'])
export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) await auth.protect()
})
```

### Step 3: Upgrade Process
```bash
# 1. Create upgrade branch
git checkout -b upgrade-clerk-sdk

# 2. Update package
npm install @clerk/nextjs@latest

# 3. Check for peer dependency issues
npm ls @clerk/nextjs

# 4. Run type checking
npm run typecheck

# 5. Run tests
npm test
```

### Step 4: Handle Common Migration Patterns

#### Middleware Migration (v5 to v6)
```typescript
// OLD: authMiddleware (deprecated)
import { authMiddleware } from '@clerk/nextjs'

export default authMiddleware({
  publicRoutes: ['/', '/sign-in', '/sign-up'],
  ignoredRoutes: ['/api/webhooks(.*)']
})

// NEW: clerkMiddleware
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublicRoute = createRouteMatcher([
  '/',
  '/sign-in(.*)',
  '/sign-up(.*)'
])

export default clerkMiddleware(async (auth, request) => {
  if (!isPublicRoute(request)) {
    await auth.protect()
  }
})