clerk-upgrade-migration

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

仓库: ComeOnOliver/skillshub
最近来源活动: 2026年3月23日 17:43
检测到的 SKILL.md 语言: 英语
星标: 58
分支: 20

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

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 <jeremy@intentsolutions.io>
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 } =  ()

# Search for synchronous auth() calls that need await
grep -rn "const.*= auth()" --include="*.ts" --include="*.tsx" | grep -v "await"

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

// BEFORE:
// import { auth, currentUser } from '@clerk/nextjs'

// AFTER:
import { auth, currentUser } from '@clerk/nextjs/server'

# 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/nextjs@5.x.x  # 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."