[PR #803] [MERGED] Update @clerk/nextjs compatibility: unsupported → partial #857

New issue

Closed

opened 2026-05-06 13:10:29 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:10:29 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/803
Author: @Shorebirdmgmt
Created: 4/9/2026
Status: ✅ Merged
Merged: 4/9/2026
Merged by: @james-elicx

Base: main ← Head: clerk-compatibility

📝 Commits (1)

bee8fad Update @clerk/nextjs compatibility from unsupported to partial

📊 Changes

2 files changed (+18 additions, -3 deletions)

View changed files

📝 packages/vinext/src/check.ts (+3 -2)
📝 tests/check.test.ts (+15 -1)

📄 Description

Summary

Updates @clerk/nextjs status in LIBRARY_SUPPORT from unsupported to partial
Adds test case for the new partial status
Fixes existing test to use @auth/nextjs for the unsupported-libraries assertion

Context

Closes #800. @clerk/nextjs was marked as unsupported with "deep Next.js middleware integration not compatible," but runtime testing shows this is overly conservative — Clerk's middleware works through vinext's existing shims.

What was tested

Built and ran a Next.js 16 App Router app with @clerk/nextjs v7.0.12 on vinext 0.0.40. Verified against Clerk's live API:

Feature	Status	Evidence
`clerkMiddleware()`	Works	Middleware runs, authenticates requests, returns correct responses
`auth.protect()`	Works	307 redirect to Clerk handshake for unauthenticated page requests
`frontendApiProxy`	Works	`/__clerk/v1/*` proxies to Clerk API with `x-clerk-trace-id` header
`ClerkProvider`	Works	Sign-in page renders with `clerk.browser.js` and publishable key
`x-clerk-auth-*` headers	Works	`x-clerk-auth-status`, `x-clerk-auth-reason` propagated on responses
Clerk handshake flow	Works	Redirect goes through `/__clerk/` proxy (frontendApiProxy working)

Why it works

Clerk's `clerkMiddleware()` uses standard Next.js middleware patterns that vinext already shims:

`NextRequest` — vinext's shim provides `cookies`, `nextUrl`, `headers`, `ip`, `geo`
`NextResponse.next()` — sets `x-middleware-next` header, which vinext processes
`NextResponse.redirect()` — standard redirect, vinext handles 3xx responses
`NextResponse.rewrite()` — sets `x-middleware-rewrite` header, vinext processes
`x-middleware-request-*` headers — Clerk's `decorateRequest()` encodes auth tokens via these headers; vinext's `applyMiddlewareRequestHeaders()` unpacks them
`x-middleware-override-headers` — Clerk uses this for request header passthrough; vinext's `buildRequestHeadersFromMiddlewareResponse()` handles it
`NextFetchEvent.waitUntil()` — vinext provides this via its `NextFetchEvent` shim

What's still WIP (why "partial" not "supported")

`auth()` in Server Components and Route Handlers uses `next/headers`'s `headers()` and `cookies()` functions to read the auth state that middleware injected. This path hasn't been verified — it depends on vinext's `next/headers` shim correctly exposing the middleware-decorated request headers.

Test plan

Existing `check.test.ts` tests pass with updated assertions
New test verifies `@clerk/nextjs` detected as `partial`
Runtime verified: build succeeds, server starts, Clerk auth flows work

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/803 **Author:** [@Shorebirdmgmt](https://github.com/Shorebirdmgmt) **Created:** 4/9/2026 **Status:** ✅ Merged **Merged:** 4/9/2026 **Merged by:** [@james-elicx](https://github.com/james-elicx) **Base:** `main` ← **Head:** `clerk-compatibility` --- ### 📝 Commits (1) - [`bee8fad`](https://github.com/cloudflare/vinext/commit/bee8fada9562a65328988875f0034f40716ee0eb) Update @clerk/nextjs compatibility from unsupported to partial ### 📊 Changes **2 files changed** (+18 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `packages/vinext/src/check.ts` (+3 -2) 📝 `tests/check.test.ts` (+15 -1) </details> ### 📄 Description ## Summary - Updates `@clerk/nextjs` status in `LIBRARY_SUPPORT` from `unsupported` to `partial` - Adds test case for the new partial status - Fixes existing test to use `@auth/nextjs` for the unsupported-libraries assertion ## Context Closes #800. `@clerk/nextjs` was marked as unsupported with "deep Next.js middleware integration not compatible," but runtime testing shows this is overly conservative — Clerk's middleware works through vinext's existing shims. ## What was tested Built and ran a Next.js 16 App Router app with `@clerk/nextjs` v7.0.12 on vinext 0.0.40. Verified against Clerk's live API: | Feature | Status | Evidence | |---------|--------|----------| | \`clerkMiddleware()\` | **Works** | Middleware runs, authenticates requests, returns correct responses | | \`auth.protect()\` | **Works** | 307 redirect to Clerk handshake for unauthenticated page requests | | \`frontendApiProxy\` | **Works** | \`/__clerk/v1/*\` proxies to Clerk API with \`x-clerk-trace-id\` header | | \`ClerkProvider\` | **Works** | Sign-in page renders with \`clerk.browser.js\` and publishable key | | \`x-clerk-auth-*\` headers | **Works** | \`x-clerk-auth-status\`, \`x-clerk-auth-reason\` propagated on responses | | Clerk handshake flow | **Works** | Redirect goes through \`/__clerk/\` proxy (frontendApiProxy working) | ## Why it works Clerk's \`clerkMiddleware()\` uses standard Next.js middleware patterns that vinext already shims: - **\`NextRequest\`** — vinext's shim provides \`cookies\`, \`nextUrl\`, \`headers\`, \`ip\`, \`geo\` - **\`NextResponse.next()\`** — sets \`x-middleware-next\` header, which vinext processes - **\`NextResponse.redirect()\`** — standard redirect, vinext handles 3xx responses - **\`NextResponse.rewrite()\`** — sets \`x-middleware-rewrite\` header, vinext processes - **\`x-middleware-request-*\` headers** — Clerk's \`decorateRequest()\` encodes auth tokens via these headers; vinext's \`applyMiddlewareRequestHeaders()\` unpacks them - **\`x-middleware-override-headers\`** — Clerk uses this for request header passthrough; vinext's \`buildRequestHeadersFromMiddlewareResponse()\` handles it - **\`NextFetchEvent.waitUntil()\`** — vinext provides this via its \`NextFetchEvent\` shim ## What's still WIP (why "partial" not "supported") \`auth()\` in Server Components and Route Handlers uses \`next/headers\`'s \`headers()\` and \`cookies()\` functions to read the auth state that middleware injected. This path hasn't been verified — it depends on vinext's \`next/headers\` shim correctly exposing the middleware-decorated request headers. ## Test plan - [x] Existing \`check.test.ts\` tests pass with updated assertions - [x] New test verifies \`@clerk/nextjs\` detected as \`partial\` - [x] Runtime verified: build succeeds, server starts, Clerk auth flows work --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>