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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1c941f8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

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

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Skipped		Jan 22, 2026 7:43pm