fix(expo): pass native proxy config to clerk

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.

.changeset/warm-poets-hammer.md

@@ -0,0 +1,5 @@
+---
+"@clerk/expo": patch
+---
+
+Pass `proxyUrl` and `domain` through Expo's native Clerk singleton.

packages/expo/src/provider/ClerkProvider.tsx

@@ -57,6 +57,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  children,
  tokenCache,
  publishableKey,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  experimental,
  __experimental_resourceCache,
@@ -80,6 +82,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  ? getClerkInstance({
  publishableKey: pk,
  tokenCache,
+ proxyUrl,
+ domain,
  __experimental_passkeys,
  __experimental_resourceCache,
  })
@@ -283,6 +287,8 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ClerkProviderProps<TUi
  key={pk}
  {...rest}
  publishableKey={pk}
+ proxyUrl={proxyUrl}
+ domain={domain}
  sdkMetadata={SDK_METADATA}
  Clerk={clerkInstance}
  standardBrowser={!isNative()}

packages/expo/src/provider/singleton/__tests__/createClerkInstance.test.ts

@@ -0,0 +1,223 @@
+import type { Clerk } from '@clerk/clerk-js';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => {
+ return {
+ constructorSpy: vi.fn(),
+ };
+});
+
+vi.mock('react-native', () => {
+ return {
+ Platform: {
+ OS: 'ios',
+ },
+ NativeModules: {},
+ TurboModuleRegistry: {
+ get: vi.fn(),
+ },
+ };
+});
+
+class MockClerk {
+ public publishableKey: string;
+ public proxyUrl: unknown;
+ public domain: unknown;
+
+ constructor(publishableKey: string, options?: { proxyUrl?: unknown; domain?: unknown }) {
+ this.publishableKey = publishableKey;
+ this.proxyUrl = options?.proxyUrl;
+ this.domain = options?.domain;
+ mocks.constructorSpy(publishableKey, options);
+ }
+
+ addListener = vi.fn();
+ __internal_onBeforeRequest = vi.fn();
+ __internal_onAfterResponse = vi.fn();
+}
+
+const loadCreateClerkInstance = async () => {
+ const mod = await import('../createClerkInstance');
+ return mod.createClerkInstance;
+};
+
+describe('createClerkInstance', () => {
+ beforeEach(() => {
+ vi.resetModules();
+ vi.clearAllMocks();
+ });
+
+ test('passes proxyUrl to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('passes domain to the native Clerk constructor', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenCalledWith('pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite.example.com',
+ });
+ });
+
+ test('reuses the singleton when the config is unchanged', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('reuses the singleton when called without options after initialization', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ const second = getClerkInstance();
+
+ expect(first).toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenCalledTimes(1);
+ });
+
+ test('recreates the singleton when proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('preserves the existing publishable key when only proxyUrl changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy-a.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: 'https://proxy-b.example.com/api/__clerk',
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when proxyUrl is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ });
+ getClerkInstance({
+ proxyUrl: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('does not carry proxy config across publishable key changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_old',
+ proxyUrl: 'https://proxy.example.com/api/__clerk',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ publishableKey: 'pk_test_new',
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_new', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+
+ test('recreates the singleton when domain changes', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ const first = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-a.example.com',
+ });
+ const second = getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite-b.example.com',
+ });
+
+ expect(first).not.toBe(second);
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: 'satellite-b.example.com',
+ });
+ });
+
+ test('recreates the singleton when domain is explicitly removed', async () => {
+ const createClerkInstance = await loadCreateClerkInstance();
+ const getClerkInstance = createClerkInstance(MockClerk as unknown as typeof Clerk);
+
+ getClerkInstance({
+ publishableKey: 'pk_test_123',
+ domain: 'satellite.example.com',
+ });
+ getClerkInstance({
+ domain: undefined,
+ });
+
+ expect(mocks.constructorSpy).toHaveBeenNthCalledWith(2, 'pk_test_123', {
+ proxyUrl: undefined,
+ domain: undefined,
+ });
+ });
+});

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -37,31 +37,77 @@ type FapiResponse = Response & {
  payload: { errors?: Array<{ code: string }> } | null;
 };
 
+type ClerkRuntimeOptions = Pick<BuildClerkOptions, 'publishableKey' | 'proxyUrl' | 'domain'>;
+type ResolvedClerkRuntimeOptions = Omit<ClerkRuntimeOptions, 'publishableKey'> & {
+ publishableKey: string;
+};
+
+function hasOwnOption<Key extends keyof ClerkRuntimeOptions>(
+ options: ClerkRuntimeOptions | undefined,
+ key: Key,
+): options is ClerkRuntimeOptions & Required<Pick<ClerkRuntimeOptions, Key>> {
+ return !!options && Object.prototype.hasOwnProperty.call(options, key);
+}
+
 let __internal_clerk: HeadlessBrowserClerk | BrowserClerk | undefined;
+let __internal_clerkOptions: ClerkRuntimeOptions | undefined;
+
+/**
+ * Resolves the next native singleton config while preserving existing values for omitted options.
+ * A publishable key change starts from a clean proxy/domain config unless those values are
+ * explicitly provided alongside the new key.
+ */
+function getUpdatedClerkOptions(
+ currentOptions: ClerkRuntimeOptions | undefined,
+ nextOptions: ClerkRuntimeOptions | undefined,
+): {
+ hasConfigChanged: boolean;
+ options: ResolvedClerkRuntimeOptions;
+} {
+ const hasNextProxyUrl = hasOwnOption(nextOptions, 'proxyUrl');
+ const hasNextDomain = hasOwnOption(nextOptions, 'domain');
+ const hasKeyChanged =
+ !!currentOptions &&
+ typeof nextOptions?.publishableKey !== 'undefined' &&
+ nextOptions.publishableKey !== currentOptions.publishableKey;
+ const hasProxyChanged = !!currentOptions && hasNextProxyUrl && nextOptions.proxyUrl !== currentOptions.proxyUrl;
+ const hasDomainChanged = !!currentOptions && hasNextDomain && nextOptions.domain !== currentOptions.domain;
+
+ return {
+ hasConfigChanged: hasKeyChanged || hasProxyChanged || hasDomainChanged,
+ options: {
+ publishableKey: nextOptions?.publishableKey ?? currentOptions?.publishableKey ?? '',
+ proxyUrl: hasKeyChanged
+ ? nextOptions?.proxyUrl
+ : hasNextProxyUrl
+ ? nextOptions.proxyUrl
+ : currentOptions?.proxyUrl,
+ domain: hasKeyChanged ? nextOptions?.domain : hasNextDomain ? nextOptions.domain : currentOptions?.domain,
+ },
+ };
+}
 
 export function createClerkInstance(ClerkClass: typeof Clerk) {
  return (options?: BuildClerkOptions): HeadlessBrowserClerk | BrowserClerk => {
+ const { tokenCache = MemoryTokenCache, __experimental_resourceCache: createResourceCache } = options || {};
  const {
- publishableKey = '',
- tokenCache = MemoryTokenCache,
- __experimental_resourceCache: createResourceCache,
- } = options || {};
+ hasConfigChanged,
+ options: { publishableKey, proxyUrl, domain },
+ } = getUpdatedClerkOptions(__internal_clerkOptions, options);
 
  if (!__internal_clerk && !publishableKey) {
  errorThrower.throwMissingPublishableKeyError();
  }
 
- // Support "hot-swapping" the Clerk instance at runtime. See JS-598 for additional details.
- const hasKeyChanged = __internal_clerk && !!publishableKey && publishableKey !== __internal_clerk.publishableKey;
-
- if (!__internal_clerk || hasKeyChanged) {
- if (hasKeyChanged) {
+ if (!__internal_clerk || hasConfigChanged) {
+ if (hasConfigChanged) {
  tokenCache.clearToken?.(CLERK_CLIENT_JWT_KEY);
  }
 
  const getToken = tokenCache.getToken;
  const saveToken = tokenCache.saveToken;
- __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
+ __internal_clerkOptions = { publishableKey, proxyUrl, domain };
+ __internal_clerk = new ClerkClass(publishableKey, { proxyUrl, domain }) as unknown as BrowserClerk;
 
  if (Platform.OS === 'ios' || Platform.OS === 'android') {
  // @ts-expect-error - This is an internal API

packages/expo/src/provider/singleton/types.ts

@@ -1,5 +1,6 @@
 import type {
  CredentialReturn,
+ DomainOrProxyUrl,
  PublicKeyCredentialCreationOptionsWithoutExtensions,
  PublicKeyCredentialRequestOptionsWithoutExtensions,
  PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -16,6 +17,8 @@ export interface IStorage {
 export type BuildClerkOptions = {
  publishableKey?: string;
  tokenCache?: TokenCache;
+ proxyUrl?: DomainOrProxyUrl['proxyUrl'];
+ domain?: DomainOrProxyUrl['domain'];
  /**
  * Note: Passkey support in Expo is currently in a limited rollout phase.
  * If you're interested in using this feature, please contact us for early access or additional details.