chore(backend,nextjs): Fix ClerkRequest instance check and keyless custom headers

[wobsoriano]

Cherry-picked from PR #7431 and PR #7445 (branched off release/core-2).

This PR includes:

• From PR chore(backend): Fix ClerkRequest helper instance check #7431: Fix ClerkRequest helper instance check using duck typing instead of instanceof to fix issues in bundled environments (TanStack React Start and others)
• From PR fix(nextjs): Comply with Server Actions async requirement #7445: Make formatMetadataHeaders async to comply with Server Actions requirements
• Also includes the srvx dependency removal from tanstack-react-start integration template

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • Improved handling of Request instances across environments to avoid mis-detection

• Refactor

  • Metadata header formatting converted to async

• Tests

  • Added tests covering request instance detection and reuse
  • Updated metadata header tests to async/await

• Chores

  • Removed an unused dependency
  • Added a placeholder changeset file

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: c8275d0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Dec 12, 2025 8:08pm

[coderabbitai]

Walkthrough

Replaces an instanceof check with duck-typing for ClerkRequest detection, converts formatMetadataHeaders to return Promise (tests updated), and removes the srvx dependency from a template package.json.

Changes

Cohort / File(s)	Change Summary
Dependency cleanup integration/templates/tanstack-react-start/package.json	Removed the srvx dependency (0.8.15) from the template's dependencies.
ClerkRequest duck-typing refactor packages/backend/src/tokens/clerkRequest.ts, packages/backend/src/tokens/__tests__/clerkRequest.test.ts	Replaced instanceof detection with duck-typing (checks for clerkUrl and cookies) when creating/identifying ClerkRequest; added tests for regular Request, existing ClerkRequest, and bundler-scoped (subclassed) Request cases.
Keyless custom headers async conversion packages/nextjs/src/server/keyless-custom-headers.ts, packages/nextjs/src/__tests__/keyless-custom-headers.test.ts	Made formatMetadataHeaders(metadata) asynchronous (Promise<Headers>); updated tests to use async/await. Implementation of header construction unchanged.
Changeset .changeset/dull-forks-agree.md	Added an empty/placeholder changeset file containing YAML separators.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Inspect clerkRequest.ts duck-typing heuristic for completeness and potential false positives.
• Verify all callers of formatMetadataHeaders are updated to await the new Promise-returning API.
• Review added tests for correctness and coverage (edge cases around subclassed Request objects).

Poem

🐰 I sniffed the code and gave a hop,

Replaced a check that always stopped,
Headers now promise to arrive,
And unused deps take a dive,
A tidy patch—now onward I hop! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title accurately summarizes the main changes: fixing ClerkRequest instance checking and making keyless custom headers async, matching the core objectives of the PR.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch rob/port-7445-and-7431

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7448

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7448

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7448

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7448

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7448

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7448

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7448

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7448

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7448

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7448

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7448

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7448

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7448

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7448

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7448

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7448

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7448

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7448

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7448

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7448

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7448

commit: c8275d0