cloudflare / cloudflare/vinext
Docs: recommended Clerk auth migration pattern (`@clerk/backend` + `@clerk/react`)
- Dominant language
- TypeScript
- Stars
- 8.8k
- Forks
- 406
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 120
Description
## Context
vinext's compatibility map correctly flags `@clerk/nextjs` as unsupported. We hit this during migration — `import { auth } from '@clerk/nextjs/server'` crashes with `require is not defined` because the ESM build has a CJS dependency chain (`require("server-only")`).
We successfully migrated by splitting Clerk usage into two packages that work cleanly with vinext:
- **Server-side auth**: `@clerk/backend` — `verifyToken()` for JWKS-verified JWT auth, `createClerkClient()` for the Clerk API
- **Client-side components**: `@clerk/react` (via `@clerk/nextjs` client-only imports like `ClerkProvider`, `SignIn`, `useAuth`) — these already work fine since they're React components, not server imports
- **Middleware**: `clerkMiddleware` from `@clerk/nextjs/server` still works in `proxy.ts` since vinext handles middleware in a separate context
## What we built
A drop-in `auth()` replacement (~60 lines) that:
1. Reads `x-clerk-auth-token` and `x-clerk-auth-status` headers (set by `clerkMiddleware`)
2. Verifies the JWT cryptographically via `@clerk/backend`'s `verifyToken()` (JWKS cached after first call)
3. Returns the same shape as `@clerk/nextjs/server`'s `auth()` — `userId`, `orgId`, `orgRole`, `has()`, `redirectToSignIn()`
This let us swap `import { auth } from '@clerk/nextjs/server'` → `import { auth } from '@/lib/auth'` across 16 files with zero behavior change. All 197 tests pass with the same mock shapes.
## Request
Would it be helpful to document this pattern in vinext's docs or compatibility guide? Clerk is a popular auth provider for Next.js apps, so other users migrating to vinext will likely hit the same issue. We're happy to contribute a docs PR if there's interest.
## Environment
- **vinext**: 0.0.8
- **@clerk/nextjs**: 6.36.5
- **@clerk/backend**: 2.29.0
- **Next.js**: 16.1.6
Contributor guide
Assessment
This issue has not been assessed yet.