clerk-upgrade-migration

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".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill automates the complex process of upgrading Clerk SDK versions, specifically targeting the transition from v5 to v6. It streamlines the migration by identifying breaking changes, refactoring deprecated middleware, updating synchronous auth calls to asynchronous patterns, and ensuring all import paths and hooks align with the latest best practices, significantly reducing manual effort and preventing runtime errors.

Use Cases

  • Migrating Next.js applications from Clerk v5 to v6 by replacing deprecated authMiddleware with the new clerkMiddleware and createRouteMatcher API.
  • Refactoring server-side code to handle asynchronous auth() and currentUser() calls required by the latest Clerk SDK updates.
  • Automatically updating import paths from legacy structures to the modern @clerk/nextjs/server and @clerk/nextjs entry points.
  • Identifying and fixing type errors or deprecation warnings triggered by major Clerk package updates in TypeScript projects.
  • Implementing a safe rollback plan and verification checklist during a major authentication infrastructure upgrade.
nameclerk-upgrade-migration
description|
allowed-toolsRead, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

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

# 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

// 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

# 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)

// 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()
  }
})

Async Auth Migration

// 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
  // ...
}

Hook Updates

// 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()

Step 5: Update Import Paths

// 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'

Step 6: Test Upgrade

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

Step 7: Rollback Plan

# 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

Version Compatibility Matrix

@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

Migration Checklist

  • Backup current package.json
  • Review changelog for breaking changes
  • Update @clerk/nextjs package
  • Update middleware to clerkMiddleware
  • Make auth() calls async
  • Update deprecated hooks
  • Fix import paths
  • Run type checking
  • Run tests
  • Test authentication flows manually
  • Deploy to staging
  • Monitor for errors
  • Deploy to production

Output

  • Updated Clerk SDK
  • Migrated breaking changes
  • All tests passing
  • Production deployment ready

Error Handling

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

Resources

Next Steps

After upgrade, review clerk-ci-integration for CI/CD updates.