clerk-upgrade-migration

name	clerk-upgrade-migration
description	Manage Clerk SDK version upgrades 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".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","clerk","migration"]

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

# 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

Step 2: Review Breaking Changes

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

• 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

# 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

Step 4: Handle Common Migration Patterns

v5 to v6: auth() is now async

// BEFORE (v5): auth() was synchronous
// const { userId } = auth()


 { userId } =  ()