Back to Details

clerk-upgrade-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clerk Upgrade & Migration

Clerk 升级与迁移

Overview

概述

Safely upgrade Clerk SDK versions and handle breaking changes.
安全升级Clerk SDK版本并处理破坏性变更。

Prerequisites

前提条件

  • Current Clerk integration working
  • Git repository with clean working state
  • Test environment available
  • 当前Clerk集成可正常工作
  • Git仓库处于干净工作状态
  • 具备测试环境

Instructions

操作步骤

Step 1: Check Current Version and Available Updates

步骤1：检查当前版本与可用更新

bash
undefined
bash
undefined

Check current version

Check current version

npm list @clerk/nextjs
npm list @clerk/nextjs

Check for updates

Check for updates

npm outdated @clerk/nextjs
npm outdated @clerk/nextjs

View changelog

View changelog

npm view @clerk/nextjs versions --json | tail -20
undefined
npm view @clerk/nextjs versions --json | tail -20
undefined

Step 2: Review Breaking Changes

步骤2：查看破坏性变更

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

步骤3：升级流程

bash
undefined
bash
undefined

1. Create upgrade branch

1. Create upgrade branch

git checkout -b upgrade-clerk-sdk
git checkout -b upgrade-clerk-sdk

2. Update package

2. Update package

npm install @clerk/nextjs@latest
npm install @clerk/nextjs@latest

3. Check for peer dependency issues

3. Check for peer dependency issues

npm ls @clerk/nextjs
npm ls @clerk/nextjs

4. Run type checking

4. Run type checking

npm run typecheck
npm run typecheck

5. Run tests

5. Run tests

npm test
undefined
npm test
undefined

Step 4: Handle Common Migration Patterns

步骤4：处理常见迁移场景

Middleware Migration (v5 to v6)

中间件迁移（v5 至 v6）

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

异步Auth迁移

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

Hook更新

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

步骤5：更新导入路径

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

步骤6：测试升级效果

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

步骤7：回滚方案

bash
undefined
bash
undefined

If upgrade fails, rollback:

If upgrade fails, rollback:

git checkout main -- package.json package-lock.json npm install
git checkout main -- package.json package-lock.json npm install

Or restore from specific version

Or restore from specific version

npm install @clerk/nextjs@5.7.1 # Previous version
undefined
npm install @clerk/nextjs@5.7.1 # Previous version
undefined

Version Compatibility Matrix

版本兼容性矩阵

@clerk/nextjsNext.jsNode.js
6.x14.x, 15.x18.x, 20.x
5.x13.x, 14.x18.x, 20.x
4.x12.x, 13.x16.x, 18.x
@clerk/nextjsNext.jsNode.js
6.x14.x, 15.x18.x, 20.x
5.x13.x, 14.x18.x, 20.x
4.x12.x, 13.x16.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
  • 备份当前package.json
  • 查看变更日志中的破坏性变更
  • 更新@clerk/nextjs包
  • 将中间件更新为clerkMiddleware
  • 为auth()调用添加await
  • 更新已弃用的Hook
  • 修复导入路径
  • 运行类型检查
  • 执行测试
  • 手动测试认证流程
  • 部署至预发布环境
  • 监控错误情况
  • 部署至生产环境

Output

输出结果

  • Updated Clerk SDK
  • Migrated breaking changes
  • All tests passing
  • Production deployment ready
  • 已更新的Clerk SDK
  • 已完成迁移的破坏性变更
  • 所有测试通过
  • 可部署至生产环境

Error Handling

错误处理

ErrorCauseSolution
Type errors after upgradeAPI changesCheck changelog, update types
Middleware not executingMatcher syntax changedUpdate matcher regex
auth() returns PromiseNow async in v6Add await to auth() calls
Import errorsPath changesUpdate to @clerk/nextjs/server
错误原因解决方案
升级后出现类型错误API变更查看变更日志，更新类型定义
中间件未执行匹配器语法变更更新匹配器正则表达式
auth()返回Promisev6中已改为异步为auth()调用添加await
导入错误路径变更更新为@clerk/nextjs/server路径

Resources

相关资源

Next Steps

后续步骤

After upgrade, review 
clerk-ci-integration
for CI/CD updates.
升级完成后，检查
clerk-ci-integration
以进行CI/CD更新。