Clerk Upgrade & Migration
Current State
!npm list @clerk/nextjs @clerk/clerk-react @clerk/express 2>/dev/null | grep clerk || echo 'No Clerk packages found'
Overview
Safely upgrade Clerk SDK versions and handle breaking changes. Covers version checking, upgrade procedures, common migration patterns, and rollback planning.
Prerequisites
- Current Clerk integration working
- Git repository with clean working state
- Test environment available for validation
Instructions
Step 1: Check Current Version and Available Updates
npm list @clerk/nextjs
npm view @clerk/nextjs version
npm outdated | grep clerk
Step 2: Review Breaking Changes
npx open-cli https://clerk.com/changelog
npx open-cli https://github.com/clerk/javascript/releases
Key version milestones to watch for:
- v5 to v6:
auth() became async (must await auth())
- v5 to v6:
authMiddleware renamed to clerkMiddleware
- v5 to v6: Import paths changed to
@clerk/nextjs/server
Step 3: Upgrade Process
git checkout -b chore/upgrade-clerk
npm install @clerk/nextjs@latest @clerk/themes@latest
npm list | grep clerk
Step 4: Handle Common Migration Patterns
v5 to v6: auth() is now async
const { userId } = await auth()
Find all affected files:
grep -rn "const.*= auth()" --include="*.ts" --include="*.tsx" | grep -v "await"
v5 to v6: Middleware migration
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isPublicRoute = createRouteMatcher(['/'])
export default clerkMiddleware(async (auth, req) => {
if (!isPublicRoute(req)) {
await auth.protect()
}
})
v5 to v6: Import path changes
import { auth, currentUser } from '@clerk/nextjs/server'
Fix import paths across codebase:
grep -rn "from '@clerk/nextjs'" --include="*.ts" --include="*.tsx" | grep -v "node_modules" | grep -v "/server"
Step 5: Update Type Definitions
declare module '@clerk/nextjs/server' {
interface AuthObject {
sessionClaims?: {
metadata?: {
role?: string
}
}
}
}
Step 6: Test Upgrade
npm run build
npm test
npm run dev
Step 7: Rollback Plan
git stash
npm install @clerk/nextjs@5.x.x
git checkout main -- package.json package-lock.json
npm install
npm run build && npm test
Output
- Clerk SDK upgraded to latest version
- Breaking changes migrated (async auth, new middleware, import paths)
- Type definitions updated
- All tests passing
- Rollback procedure documented
Error Handling
| Error | Cause | Solution |
|---|
| Type errors after upgrade | API signature changes | Add await to auth(), update imports |
authMiddleware is not exported | Renamed in v6 | Use clerkMiddleware from @clerk/nextjs/server |
auth() returns Promise | Now async in v6 | Add await to all auth() calls |
| Import not found | Path changed | Use @clerk/nextjs/server for server-side imports |
| Version mismatch | Clerk packages on different versions | Update all @clerk/* packages together |
Examples
Automated Migration Script
#!/bin/bash
set -euo pipefail
echo "=== Clerk v5 to v6 Migration ==="
echo "Adding await to auth() calls..."
find . -name "*.ts" -o -name "*.tsx" | xargs grep -l "const.*= auth()" 2>/dev/null | while read file; do
sed -i 's/const \(.*\) = auth()/const \1 = await auth()/g' "$file"
echo " Fixed: $file"
done
echo "Updating import paths..."
find . -name "*.ts" -o -name "*.tsx" | xargs grep -l "from '@clerk/nextjs'" 2>/dev/null | while read file; do
if grep -q "auth\|currentUser\|clerkClient" "$file"; then
sed -i "s/from '@clerk\/nextjs'/from '@clerk\/nextjs\/server'/g" "$file"
echo " Fixed: $file"
fi
done
echo "Done. Run 'npm run build' to check for remaining issues."
Resources
Next Steps
After upgrade, review clerk-ci-integration for CI/CD updates.
