feat(backend): Add Frontend API proxy helpers

[brkalow]

Description

Adds Frontend API proxy support to clerkMiddleware for both Next.js and Express. This enables scenarios where direct communication with Clerk's API is blocked or needs to go through the application server.

API

Next.js

import { clerkMiddleware } from '@clerk/nextjs/server';

export default clerkMiddleware({
  // Enable proxy with defaults (path: '/__clerk')
  frontendApiProxy: {
    enabled: true,
  },
});

// Or with multi-domain support using a function
export default clerkMiddleware({
  frontendApiProxy: {
    enabled: (url) => url.hostname === 'app.example.com',
  },
});

// Custom proxy path
export default clerkMiddleware({
  frontendApiProxy: {
    enabled: true,
    path: '/custom-clerk-proxy',
  },
});

Express

import express from 'express';
import { clerkMiddleware } from '@clerk/express';

const app = express();

// Enable proxy with defaults (path: '/__clerk')
app.use(clerkMiddleware({ frontendApiProxy: { enabled: true } }));

// Custom proxy path
app.use(clerkMiddleware({ frontendApiProxy: { enabled: true, path: '/my-proxy' } }));

// Disable proxy
app.use(clerkMiddleware({ frontendApiProxy: { enabled: false } }));

Key Features

• Embedded in clerkMiddleware: No separate middleware needed - proxy handling is built into clerkMiddleware
• Auto-derived proxyUrl: The proxyUrl for handshake redirects is automatically derived from the frontendApiProxy config
• Multi-domain support (Next.js): Use a function for enabled to conditionally enable proxy based on request URL
• Streaming body support: Request and response bodies are streamed for efficient handling
• Header rewriting: Redirect responses are automatically rewritten to use the proxy URL

Type of change

• 🌟 New feature

Testing

• Unit tests added for proxy functionality in both Next.js and Express
• Tests cover: proxy path matching, proxyUrl derivation, multi-domain support, header handling

Summary by CodeRabbit

• New Features

  • Frontend API proxy added across backend, Next.js, and Express with configurable proxy path, automatic proxy URL derivation, and App Router handler helpers.

• Behavior

  • Proxy streams requests/responses, preserves queries/headers, manages X-Forwarded headers, strips hop-by-hop headers, and rewrites internal redirects.

• Tests

  • Extensive tests for routing, header propagation, error handling, redirects, and multi-domain scenarios.

• Documentation

  • Changeset documenting the Frontend API proxy feature.

[changeset-bot]

🦋 Changeset detected

Latest commit: adaf188

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/backend	Minor
@clerk/nextjs	Minor
@clerk/express	Minor
@clerk/shared	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/fastify	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/react	Patch
@clerk/ui	Patch
@clerk/vue	Patch

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	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 13, 2026 4:10pm

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/nextjs/src/server/index.ts`:
- Around line 78-87: Remove the new barrel re-exports from index.ts: delete the
export block that re-exports clerkFrontendApiProxy,
createFrontendApiProxyHandlers and the types FrontendApiProxyHandlers,
FrontendApiProxyOptions, NextFrontendApiProxyOptions; instead ensure
consumers/importers use the dedicated module path './proxy' directly (or add a
new explicit entrypoint file if needed) and update any internal imports to
reference './proxy' rather than the package root to avoid expanding the barrel
and preventing possible circular dependencies.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@packages/express/src/authenticateRequest.ts`:
- Around line 132-136: The proxy path check in authenticateRequest.ts fails when
request.originalUrl contains a query string; update the proxy matching logic to
extract only the pathname (strip the query string) from request.originalUrl ||
request.url before comparing to proxyPath. In practice, compute a
requestPathName (or reuse request.path) that excludes the query string, then use
that value in the existing if checks that reference proxyEnabled, requestPath
(or requestPathName) and proxyPath (including the startsWith(proxyPath + '/')
check).
- Around line 176-188: The code that auto-derives proxyUrl when proxyEnabled and
!options.proxyUrl uses request.headers['x-forwarded-proto'] and
request.headers['x-forwarded-host'] directly, which fails for comma-separated
header chains; update the extraction in the resolvedOptions block (around
proxyEnabled, options.proxyUrl, resolvedOptions, derivedProxyUrl, proxyPath) to
split the header value on ',' and take the first item, trimming whitespace (e.g.
const protoHeader = Array.isArray(forwardedProto) ? forwardedProto[0] :
forwardedProto; const protoValue = (protoHeader || '').split(',')[0].trim(); and
same for host) before computing protocol, host and derivedProxyUrl so the first
forwarded value is used.

[jacekradko]

[nit] I think this might be duped

[jacekradko]

[nit] I think it would make sense to make this a required configuration value so it's easy to grok if the feature is on or off

[brkalow]

@jacekradko required if frontendApiProxy is present right?

[jacekradko]

Yep

[jacekradko]

Suggested change

	---
	'@clerk/shared': minor
	---

[jacekradko]

Just minor comments