Upgrade Clerk SDK versions and handle breaking changes. Use when upgrading Clerk packages, migrating to new SDK versions, or handling deprecation warnings. Trigger with phrases like "upgrade clerk", "clerk migration", "update clerk SDK", "clerk breaking changes".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill clerk-upgrade-migrationLoading…
!npm list @clerk/nextjs @clerk/clerk-react @clerk/express 2>/dev/null | grep clerk || echo 'No Clerk packages found'
Safely upgrade Clerk SDK versions and handle breaking changes. Covers version checking, upgrade procedures, common migration patterns, and rollback planning.
# Check installed version
npm list @clerk/nextjs
# Check latest available
npm view @clerk/nextjs version
# Check all Clerk packages and their versions
npm outdated | grep clerk
# View changelog for the target version
npx open-cli https://clerk.com/changelog
# Check GitHub releases for migration notes
npx open-cli https://github.com/clerk/javascript/releases
Key version milestones to watch for:
auth() became async (must await auth())authMiddleware renamed to clerkMiddleware@clerk/nextjs/server# Create upgrade branch
git checkout -b chore/upgrade-clerk
# Upgrade all Clerk packages together (they must version-match)
npm install @clerk/nextjs@latest @clerk/themes@latest
# If using other Clerk packages:
# npm install @clerk/clerk-react@latest @clerk/express@latest @clerk/backend@latest
# Verify no version mismatches
npm list | grep clerk
v5 to v6: auth() is now async
// BEFORE (v5): auth() was synchronous
// const { userId } = auth()
// AFTER (v6): auth() returns a Promise
const { userId } = await auth()
Find all affected files:
# Search for synchronous auth() calls that need await
grep -rn "const.*= auth()" --include="*.ts" --include="*.tsx" | grep -v "await"
v5 to v6: Middleware migration
// 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()
}
})
v5 to v6: Import path changes
// BEFORE:
// import { auth, currentUser } from '@clerk/nextjs'
// AFTER:
import { auth, currentUser } from '@clerk/nextjs/server'
Fix import paths across codebase:
# Find files using old import path
grep -rn "from '@clerk/nextjs'" --include="*.ts" --include="*.tsx" | grep -v "node_modules" | grep -v "/server"
// If using custom type extensions, update them
// BEFORE:
// declare module '@clerk/nextjs' { ... }
// AFTER:
declare module '@clerk/nextjs/server' {
interface AuthObject {
// Custom session claims type
sessionClaims?: {
metadata?: {
role?: string
}
}
}
}
# Build to catch type errors
npm run build
# Run tests
npm test
# Start dev server and test manually
npm run dev
# Test critical flows:
# 1. Sign in with email/password
# 2. Sign in with OAuth
# 3. Protected route access
# 4. API route authentication
# 5. Webhook endpoint
# 6. Sign out
# If upgrade fails, rollback to previous version
git stash # Save any manual changes
# Install previous version
npm install @clerk/[email protected] # Replace with your previous version
# Or restore from git
git checkout main -- package.json package-lock.json
npm install
# Verify rollback works
npm run build && npm test
| 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 |
#!/bin/bash
# scripts/migrate-clerk-v6.sh
set -euo pipefail
echo "=== Clerk v5 to v6 Migration ==="
# 1. Fix auth() calls (add await)
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
# 2. Fix import paths
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."
After upgrade, review clerk-ci-integration for CI/CD updates.
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).