feat(react): Add env variable fallback for publishableKey in Vite apps (#7634)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: brkalow

.changeset/warm-keys-glow.md

@@ -0,0 +1,5 @@
+---
+'@clerk/react': minor
+---
+
+Add automatic environment variable fallback for Vite applications. When `publishableKey` is not explicitly provided to `ClerkProvider`, the SDK now checks for `VITE_CLERK_PUBLISHABLE_KEY` and `CLERK_PUBLISHABLE_KEY` environment variables.

integration/templates/custom-flows-react-vite/src/main.tsx

@@ -9,19 +9,11 @@ import { SignUp } from './routes/SignUp';
 import { Protected } from './routes/Protected';
 import { Waitlist } from './routes/Waitlist';
 
-// Import your Publishable Key
-const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
-
-if (!PUBLISHABLE_KEY) {
-  throw new Error('Add your Clerk Publishable Key to the .env file');
-}
-
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
     <div className='bg-muted flex min-h-svh flex-col items-center justify-center gap-6 p-6 md:p-10'>
       <div className='flex w-full max-w-sm flex-col gap-6'>
         <ClerkProvider
-          publishableKey={PUBLISHABLE_KEY}
           clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
           clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL as string}
           appearance={{

integration/templates/react-vite/src/main.tsx

@@ -28,8 +28,6 @@ const Root = () => {
   const navigate = useNavigate();
   return (
     <ClerkProvider
-      // @ts-ignore
-      publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY as string}
       clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
       clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL as string}
       routerPush={(to: string) => navigate(to)}

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -11,6 +11,7 @@ import React from 'react';
 
 import { IsomorphicClerk } from '../isomorphicClerk';
 import type { IsomorphicClerkOptions } from '../types';
+import { mergeWithEnv } from '../utils';
 import { AuthContext } from './AuthContext';
 import { IsomorphicClerkContext } from './IsomorphicClerkContext';
 
@@ -24,7 +25,9 @@ export type ClerkContextProviderState = Resources;
 
 export function ClerkContextProvider(props: ClerkContextProvider) {
   const { isomorphicClerkOptions, initialState, children } = props;
-  const { isomorphicClerk: clerk, clerkStatus } = useLoadedIsomorphicClerk(isomorphicClerkOptions);
+  // Merge options with environment variable fallbacks (supports Vite's VITE_CLERK_* env vars)
+  const mergedOptions = mergeWithEnv(isomorphicClerkOptions);
+  const { isomorphicClerk: clerk, clerkStatus } = useLoadedIsomorphicClerk(mergedOptions);
 
   const [state, setState] = React.useState<ClerkContextProviderState>({
     client: clerk.client as ClientResource,
@@ -111,17 +114,17 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
   );
 }
 
-const useLoadedIsomorphicClerk = (options: IsomorphicClerkOptions) => {
-  const isomorphicClerkRef = React.useRef(IsomorphicClerk.getOrCreateInstance(options));
+const useLoadedIsomorphicClerk = (mergedOptions: IsomorphicClerkOptions) => {
+  const isomorphicClerkRef = React.useRef(IsomorphicClerk.getOrCreateInstance(mergedOptions));
   const [clerkStatus, setClerkStatus] = React.useState(isomorphicClerkRef.current.status);
 
   React.useEffect(() => {
-    void isomorphicClerkRef.current.__internal_updateProps({ appearance: options.appearance });
-  }, [options.appearance]);
+    void isomorphicClerkRef.current.__internal_updateProps({ appearance: mergedOptions.appearance });
+  }, [mergedOptions.appearance]);
 
   React.useEffect(() => {
-    void isomorphicClerkRef.current.__internal_updateProps({ options });
-  }, [options.localization]);
+    void isomorphicClerkRef.current.__internal_updateProps({ options: mergedOptions });
+  }, [mergedOptions.localization]);
 
   React.useEffect(() => {
     isomorphicClerkRef.current.on('status', setClerkStatus);

packages/react/src/utils/__tests__/envVariables.test.ts

@@ -0,0 +1,110 @@
+import * as getEnvVariableModule from '@clerk/shared/getEnvVariable';
+import type { IsomorphicClerkOptions } from '@clerk/shared/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { mergeWithEnv } from '../envVariables';
+
+// Mock getEnvVariable to control env var behavior in tests
+vi.mock('@clerk/shared/getEnvVariable', () => ({
+  getEnvVariable: vi.fn(() => ''),
+}));
+
+describe('mergeWithEnv', () => {
+  const mockedGetEnvVariable = vi.mocked(getEnvVariableModule.getEnvVariable);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns passed-in publishableKey when provided', () => {
+    mockedGetEnvVariable.mockReturnValue('should_not_be_used');
+
+    const options: IsomorphicClerkOptions = {
+      publishableKey: 'pk_test_explicit',
+    };
+
+    const result = mergeWithEnv(options);
+
+    expect(result.publishableKey).toBe('pk_test_explicit');
+  });
+
+  it('falls back to VITE_CLERK_PUBLISHABLE_KEY env var when option is undefined', () => {
+    mockedGetEnvVariable.mockImplementation((name: string) => {
+      if (name === 'VITE_CLERK_PUBLISHABLE_KEY') {
+        return 'pk_test_vite';
+      }
+      return '';
+    });
+
+    const result = mergeWithEnv({} as any);
+
+    expect(result.publishableKey).toBe('pk_test_vite');
+  });
+
+  it('falls back to CLERK_PUBLISHABLE_KEY when VITE_ prefixed not set', () => {
+    mockedGetEnvVariable.mockImplementation((name: string) => {
+      if (name === 'CLERK_PUBLISHABLE_KEY') {
+        return 'pk_test_node';
+      }
+      return '';
+    });
+
+    const result = mergeWithEnv({} as any);
+
+    expect(result.publishableKey).toBe('pk_test_node');
+  });
+
+  it('prioritizes VITE_ prefixed env var over non-prefixed', () => {
+    mockedGetEnvVariable.mockImplementation((name: string) => {
+      const envVars: Record<string, string> = {
+        VITE_CLERK_PUBLISHABLE_KEY: 'pk_test_vite',
+        CLERK_PUBLISHABLE_KEY: 'pk_test_node',
+      };
+      return envVars[name] || '';
+    });
+
+    const result = mergeWithEnv({} as any);
+
+    expect(result.publishableKey).toBe('pk_test_vite');
+  });
+
+  it('does NOT fall back when publishableKey is empty string (framework SDK behavior)', () => {
+    mockedGetEnvVariable.mockReturnValue('pk_test_vite');
+
+    const result = mergeWithEnv({
+      publishableKey: '',
+    });
+
+    // Should preserve empty string, not fall back to env var
+    expect(result.publishableKey).toBe('');
+  });
+
+  it('returns undefined publishableKey when neither option nor env var is set', () => {
+    mockedGetEnvVariable.mockReturnValue('');
+
+    const result = mergeWithEnv({} as any);
+
+    // When env var is not set, we don't add the property
+    expect(result.publishableKey).toBeUndefined();
+  });
+
+  it('preserves other options that are not env-var backed', () => {
+    mockedGetEnvVariable.mockReturnValue('');
+
+    const options: IsomorphicClerkOptions = {
+      publishableKey: 'pk_test',
+      appearance: { variables: { colorPrimary: 'red' } },
+      localization: { signIn: { start: { title: 'Hello' } } },
+      signInUrl: '/custom-sign-in',
+      signUpUrl: '/custom-sign-up',
+    };
+
+    const result = mergeWithEnv(options);
+
+    expect(result.publishableKey).toBe('pk_test');
+    expect(result.appearance).toEqual({ variables: { colorPrimary: 'red' } });
+    expect(result.localization).toEqual({ signIn: { start: { title: 'Hello' } } });
+    expect(result.signInUrl).toBe('/custom-sign-in');
+    expect(result.signUpUrl).toBe('/custom-sign-up');
+  });
+});

packages/react/src/utils/envVariables.ts

@@ -0,0 +1,61 @@
+import { getEnvVariable } from '@clerk/shared/getEnvVariable';
+
+import type { IsomorphicClerkOptions } from '../types';
+
+/**
+ * Gets an environment variable value, checking for Vite's VITE_ prefix first.
+ * This allows React SDK users with Vite to use VITE_CLERK_* env vars
+ * (which Vite exposes client-side) without manual configuration.
+ *
+ * Note: Empty string values are treated as "not set" and will fall through to
+ * the next env var in the chain. This is intentional since empty values are
+ * typically invalid for these options.
+ *
+ * @param name - The environment variable name without prefix (e.g., 'CLERK_PUBLISHABLE_KEY')
+ * @returns The value of the environment variable, or empty string if not found
+ */
+const getEnvVar = (name: string): string => {
+  // Check for Vite-prefixed env var first (client-side exposed)
+  // Then fall back to unprefixed version (for SSR, Node.js, etc.)
+  // Note: Uses || so empty string falls through to the next check
+  return getEnvVariable(`VITE_${name}`) || getEnvVariable(name);
+};
+
+/**
+ * Helper to get env fallback only when the option is undefined.
+ * We check for undefined specifically (not falsy) to avoid conflicting with framework SDKs
+ * that may pass an empty string when their env var is not set.
+ *
+ * Returns the env var value only if it's non-empty, otherwise returns undefined
+ * to preserve the original behavior when no env var is set.
+ */
+const withEnvFallback = (value: string | undefined, envVarName: string): string | undefined => {
+  if (value !== undefined) {
+    return value;
+  }
+  const envValue = getEnvVar(envVarName);
+  return envValue || undefined;
+};
+
+/**
+ * Merges ClerkProvider options with environment variable fallbacks.
+ * This supports Vite users who set VITE_CLERK_* or CLERK_* env vars.
+ * Passed-in options always take priority over environment variables.
+ *
+ * Supported environment variables:
+ * - VITE_CLERK_PUBLISHABLE_KEY / CLERK_PUBLISHABLE_KEY
+ *
+ * @param options - The options passed to ClerkProvider
+ * @returns Options with environment variable fallbacks applied
+ */
+export const mergeWithEnv = (options: IsomorphicClerkOptions): IsomorphicClerkOptions => {
+  // Get env fallback values (undefined if not set)
+  const publishableKey = withEnvFallback(options.publishableKey, 'CLERK_PUBLISHABLE_KEY');
+
+  // Only add publishableKey to result if it has a defined value
+  // URL fallbacks removed due to compatibility issues with @clerk/react-router
+  return {
+    ...options,
+    ...(publishableKey !== undefined && { publishableKey }),
+  };
+};

packages/react/src/utils/index.ts

@@ -1,4 +1,5 @@
 export * from './childrenUtils';
+export * from './envVariables';
 export * from './isConstructor';
 export * from './useMaxAllowedInstancesGuard';
 export * from './useCustomElementPortal';