feat(*): auto-proxy for eligible hosts

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {

.changeset/auto-proxy-vercel-subdomains.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+---
+
+Auto-proxy FAPI requests for `.vercel.app` subdomains. When deployed to a `.vercel.app` domain without explicit proxy or domain configuration, the SDK automatically routes Frontend API requests through `/__clerk` on the app's own origin. This enables Clerk production mode on Vercel deployments without manual proxy setup.

packages/backend/src/tokens/__tests__/authenticateContext.test.ts

@@ -258,6 +258,71 @@ describe('AuthenticateContext', () => {
  });
  });
 
+ describe('auto-proxy for eligible hosts', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ VERCEL_TARGET_ENV: 'production',
+ VERCEL_PROJECT_PRODUCTION_URL: 'myapp-abc123.vercel.app',
+ };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('auto-derives proxyUrl when Vercel env vars indicate production vercel.app', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ it('does NOT auto-derive proxyUrl for development keys', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkTest,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('does NOT auto-derive proxyUrl when Vercel env vars are absent', async () => {
+ delete process.env.VERCEL_TARGET_ENV;
+ delete process.env.VERCEL_PROJECT_PRODUCTION_URL;
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+
+ it('explicit proxyUrl takes precedence over auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+
+ expect(context.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ it('explicit domain skips auto-detection', async () => {
+ const clerkRequest = createClerkRequest(new Request('https://myapp-abc123.vercel.app/dashboard'));
+ const context = await createAuthenticateContext(clerkRequest, {
+ publishableKey: pkLive,
+ domain: 'clerk.myapp.com',
+ });
+
+ expect(context.proxyUrl).toBeUndefined();
+ });
+ });
+
  // Added these tests to verify that the generated sha-1 is the same as the one used in cookie assignment
  // Tests copied from packages/shared/src/__tests__/keys.test.ts
  describe('getCookieSuffix(publishableKey, subtle)', () => {

packages/backend/src/tokens/authenticateContext.ts

@@ -1,4 +1,5 @@
 import { buildAccountsBaseUrl } from '@clerk/shared/buildAccountsBaseUrl';
+import { getAutoProxyUrlFromEnvironment } from '@clerk/shared/proxy';
 import type { Jwt } from '@clerk/shared/types';
 import { isCurrentDevAccountPortalOrigin, isLegacyDevAccountPortalOrigin } from '@clerk/shared/url';
 
@@ -70,6 +71,18 @@ class AuthenticateContext implements AuthenticateContext {
  private clerkRequest: ClerkRequest,
  options: AuthenticateRequestOptions,
  ) {
+ // Auto-detect proxy for supported platform deployments using environment
+ // variables (e.g. VERCEL_TARGET_ENV, VERCEL_PROJECT_PRODUCTION_URL) instead
+ // of request headers, which avoids X-Forwarded-Host spoofing concerns.
+ const autoProxyPath = getAutoProxyUrlFromEnvironment({
+ publishableKey: options.publishableKey ?? '',
+ hasProxyUrl: !!options.proxyUrl,
+ hasDomain: !!options.domain,
+ });
+ if (autoProxyPath) {
+ options = { ...options, proxyUrl: `${clerkRequest.clerkUrl.origin}${autoProxyPath}` };
+ }
+
  if (options.acceptsToken === TokenType.M2MToken || options.acceptsToken === TokenType.ApiKey) {
  // For non-session tokens, we only want to set the header values.
  this.initHeaderValues();

packages/clerk-js/src/core/__tests__/clerk.test.ts

@@ -2516,6 +2516,86 @@ describe('Clerk singleton', () => {
  });
  });
  });
+
+ describe('auto-detection for eligible hosts', () => {
+ const originalLocation = window.location;
+
+ afterEach(() => {
+ Object.defineProperty(window, 'location', {
+ value: originalLocation,
+ writable: true,
+ });
+ });
+
+ test('auto-derives proxyUrl for production instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('https://myapp-abc123.vercel.app/__clerk');
+ });
+
+ test('does NOT auto-derive proxyUrl for development instances on eligible hosts', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(developmentPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('does NOT auto-derive proxyUrl for ineligible domains', () => {
+ const sut = new Clerk(productionPublishableKey);
+ expect(sut.proxyUrl).toBe('');
+ });
+
+ test('explicit proxyUrl takes precedence over auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ proxyUrl: 'https://custom-proxy.example.com/__clerk',
+ });
+ expect(sut.proxyUrl).toBe('https://custom-proxy.example.com/__clerk');
+ });
+
+ test('explicit domain skips auto-detection', () => {
+ Object.defineProperty(window, 'location', {
+ value: {
+ ...originalLocation,
+ hostname: 'myapp-abc123.vercel.app',
+ origin: 'https://myapp-abc123.vercel.app',
+ href: 'https://myapp-abc123.vercel.app/dashboard',
+ },
+ writable: true,
+ });
+
+ const sut = new Clerk(productionPublishableKey, {
+ domain: 'clerk.myapp.com',
+ });
+ expect(sut.proxyUrl).toBe('');
+ });
+ });
  });
 
  describe('buildUrlWithAuth', () => {

packages/clerk-js/src/core/clerk.ts

@@ -38,7 +38,13 @@ import { windowNavigate } from '@clerk/shared/internal/clerk-js/windowNavigate';
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { logger } from '@clerk/shared/logger';
 import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
-import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
+import {
+ AUTO_PROXY_PATH,
+ isHttpOrHttps,
+ isValidProxyUrl,
+ proxyUrlToAbsoluteURL,
+ shouldAutoProxy,
+} from '@clerk/shared/proxy';
 import {
  eventPrebuiltComponentMounted,
  eventPrebuiltComponentOpened,
@@ -361,7 +367,14 @@ export class Clerk implements ClerkInterface {
  if (!isValidProxyUrl(_unfilteredProxy)) {
  errorThrower.throwInvalidProxyUrl({ url: _unfilteredProxy });
  }
- return proxyUrlToAbsoluteURL(_unfilteredProxy);
+ const resolved = proxyUrlToAbsoluteURL(_unfilteredProxy);
+ if (resolved) {
+ return resolved;
+ }
+ // Auto-detect when no explicit proxy or domain is configured (production only)
+ if (!this.#domain && this.#instanceType === 'production' && shouldAutoProxy(window.location.hostname)) {
+ return `${window.location.origin}${AUTO_PROXY_PATH}`;
+ }
  }
 
  if (typeof this.#proxyUrl === 'function') {

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -86,4 +86,24 @@ describe('DynamicClerkScripts', () => {
  expect(html).not.toContain('nonce="test');
  expect(html).not.toContain('nonce="csp');
  });
+
+ it('renders initial script tags with relative proxied asset URLs', async () => {
+ mockHeaders.mockResolvedValue(
+ new Map([
+ ['X-Nonce', null],
+ ['Content-Security-Policy', ''],
+ ]),
+ );
+
+ const html = await render(
+ DynamicClerkScripts({
+ ...defaultProps,
+ proxyUrl: '/__clerk',
+ }),
+ );
+
+ expect(html).toContain('src="/__clerk/npm/@clerk/clerk-js@');
+ expect(html).toContain('href="/__clerk/npm/@clerk/ui@');
+ expect(html).toContain('data-clerk-proxy-url="/__clerk"');
+ });
 });

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -1326,6 +1326,40 @@ describe('frontendApiProxy multi-domain support', () => {
  });
 });
 
+describe('auto-proxy for eligible hosts', () => {
+ const productionPublishableKey = 'pk_live_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
+
+ it('auto-intercepts /__clerk/* requests on eligible hostnames', async () => {
+ const req = new NextRequest(new URL('/__clerk/v1/client', 'https://myapp-abc123.vercel.app').toString(), {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ // Proxy should intercept the request — authenticateRequest should NOT be called
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+
+ it('uses request.nextUrl for auto-detection', async () => {
+ const req = new NextRequest('http://127.0.0.1:3000/__clerk/v1/client', {
+ method: 'GET',
+ headers: new Headers(),
+ });
+
+ Object.defineProperty(req, 'nextUrl', {
+ value: new URL('https://myapp-abc123.vercel.app/__clerk/v1/client'),
+ configurable: true,
+ });
+
+ const resp = await clerkMiddleware({ publishableKey: productionPublishableKey })(req, {} as NextFetchEvent);
+
+ expect((await clerkClient()).authenticateRequest).not.toBeCalled();
+ expect(resp?.status).toBeDefined();
+ });
+});
+
 describe('contentSecurityPolicy option', () => {
  it('forwards CSP headers as request headers when strict mode is enabled', async () => {
  const resp = await clerkMiddleware({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -21,9 +21,10 @@ import {
  TokenType,
 } from '@clerk/backend/internal';
 import { clerkFrontendApiProxy, DEFAULT_PROXY_PATH, matchProxyPath } from '@clerk/backend/proxy';
-import { parsePublishableKey } from '@clerk/shared/keys';
+import { isProductionFromPublishableKey, parsePublishableKey } from '@clerk/shared/keys';
 import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isMalformedURLError } from '@clerk/shared/pathMatcher';
+import { shouldAutoProxy } from '@clerk/shared/proxy';
 import { notFound as nextjsNotFound } from 'next/navigation';
 import type { NextMiddleware, NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
@@ -35,7 +36,7 @@ import type { Logger, LoggerNoCommit } from '../utils/debugLogger';
 import { withLogger } from '../utils/debugLogger';
 import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
-import { PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
+import { DOMAIN, PROXY_URL, PUBLISHABLE_KEY, SECRET_KEY, SIGN_IN_URL, SIGN_UP_URL } from './constants';
 import { type ContentSecurityPolicyOptions, createContentSecurityPolicyHeaders } from './content-security-policy';
 import { errorThrower } from './errorThrower';
 import { getHeader } from './headers-utils';
@@ -161,12 +162,20 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
  );
 
  // Handle Frontend API proxy requests early, before authentication
- const frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+ const requestUrl = new URL(request.nextUrl.href);
+ let frontendApiProxyConfig = resolvedParams.frontendApiProxy;
+
+ // Auto-detect when no explicit proxy or domain is configured
+ const hasExplicitProxyOrDomain = resolvedParams.proxyUrl || PROXY_URL || resolvedParams.domain || DOMAIN;
+ if (!frontendApiProxyConfig && !hasExplicitProxyOrDomain && isProductionFromPublishableKey(publishableKey)) {
+ if (shouldAutoProxy(requestUrl.hostname)) {
+ frontendApiProxyConfig = { enabled: true };
+ }
+ }
  if (frontendApiProxyConfig) {
  const { enabled, path: proxyPath = DEFAULT_PROXY_PATH } = frontendApiProxyConfig;
 
  // Resolve enabled - either boolean or function
- const requestUrl = new URL(request.url);
  const isEnabled = typeof enabled === 'function' ? enabled(requestUrl) : enabled;
 
  if (isEnabled && matchProxyPath(request, { proxyPath })) {