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".
/plugin marketplace add jeremylongshore/claude-code-plugins-plus-skills/plugin install clerk-pack@claude-code-plugins-plusThis skill is limited to using the following tools:
Safely upgrade Clerk SDK versions and handle breaking changes.
# Check current version
npm list @clerk/nextjs
# Check for updates
npm outdated @clerk/nextjs
# View changelog
npm view @clerk/nextjs versions --json | tail -20
// 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()
})
# 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
// 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()
}
})
// OLD: Synchronous auth
import { auth } from '@clerk/nextjs'
export function GET() {
const { userId } = auth() // Synchronous
// ...
}
// NEW: Async auth
import { auth } from '@clerk/nextjs/server'
export async function GET() {
const { userId } = await auth() // Async
// ...
}
// OLD: useAuth() changes
const { isSignedIn, isLoaded } = useAuth()
// NEW: Check specific deprecations
// useAuth() still works but some properties changed
// OLD: Deprecated organization hooks
import { useOrganization } from '@clerk/nextjs'
const { membership } = useOrganization()
// NEW: Updated API
import { useOrganization } from '@clerk/nextjs'
const { organization, membership } = useOrganization()
// Server imports (Next.js App Router)
import { auth, currentUser, clerkClient } from '@clerk/nextjs/server'
// Client imports
import { useUser, useAuth, useClerk } from '@clerk/nextjs'
// Component imports
import {
ClerkProvider,
SignIn,
SignUp,
UserButton,
SignInButton,
SignUpButton
} from '@clerk/nextjs'
// tests/clerk-upgrade.test.ts
import { describe, it, expect } from 'vitest'
describe('Clerk Upgrade Validation', () => {
it('auth() returns userId for authenticated users', async () => {
// Mock or integration test
})
it('middleware protects routes correctly', async () => {
// Test protected routes return 401/redirect
})
it('webhooks still verify correctly', async () => {
// Test webhook signature verification
})
})
# If upgrade fails, rollback:
git checkout main -- package.json package-lock.json
npm install
# Or restore from specific version
npm install @clerk/nextjs@5.7.1 # Previous version
| @clerk/nextjs | Next.js | Node.js |
|---|---|---|
| 6.x | 14.x, 15.x | 18.x, 20.x |
| 5.x | 13.x, 14.x | 18.x, 20.x |
| 4.x | 12.x, 13.x | 16.x, 18.x |
| Error | Cause | Solution |
|---|---|---|
| Type errors after upgrade | API changes | Check changelog, update types |
| Middleware not executing | Matcher syntax changed | Update matcher regex |
| auth() returns Promise | Now async in v6 | Add await to auth() calls |
| Import errors | Path changes | Update to @clerk/nextjs/server |
After upgrade, review clerk-ci-integration for CI/CD updates.