feat(astro,nuxt,react-router,tanstack-react-start): Env-var to suppress dev keys warning (#8402)

Author: jacekradko

.changeset/quiet-dev-keys-warning.md

@@ -0,0 +1,16 @@
+---
+'@clerk/astro': minor
+'@clerk/nuxt': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+'@clerk/shared': patch
+---
+
+Add an env-var shortcut for `unsafe_disableDevelopmentModeConsoleWarning` across the Astro, Nuxt, React Router, and TanStack Start integrations so the development-keys console warning can be suppressed without threading the option through `<ClerkProvider>` manually:
+
+- Astro: `PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`
+- Nuxt: `NUXT_PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`
+- React Router: `VITE_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING` (or `CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`)
+- TanStack Start: `VITE_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING` (or `CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`)
+
+The Next.js equivalent (`NEXT_PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`) already existed; the JSDoc on `unsafe_disableDevelopmentModeConsoleWarning` now lists every framework's env-var shortcut and clarifies that suppressing the warning at source also keeps it from being mirrored to the dev-server terminal (e.g. Next.js with `experimental.browserDebugInfoInTerminal`).

packages/astro/src/internal/__tests__/merge-env-vars-with-params.test.ts

@@ -0,0 +1,19 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { mergeEnvVarsWithParams } from '../merge-env-vars-with-params';
+
+describe('mergeEnvVarsWithParams', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('preserves an explicit unsafe_disableDevelopmentModeConsoleWarning false when env is true', () => {
+    vi.stubEnv('PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING', 'true');
+
+    const result = mergeEnvVarsWithParams({
+      unsafe_disableDevelopmentModeConsoleWarning: false,
+    });
+
+    expect(result.unsafe_disableDevelopmentModeConsoleWarning).toBe(false);
+  });
+});

packages/astro/src/internal/merge-env-vars-with-params.ts

@@ -42,6 +42,7 @@ const mergeEnvVarsWithParams = (
     __internal_clerkUIUrl: paramClerkUIUrl,
     __internal_clerkUIVersion: paramClerkUIVersion,
     prefetchUI: paramPrefetchUI,
+    unsafe_disableDevelopmentModeConsoleWarning: paramUnsafeDisableDevelopmentModeConsoleWarning,
     ...rest
   } = params || {};
 
@@ -65,6 +66,9 @@ const mergeEnvVarsWithParams = (
       disabled: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DISABLED),
       debug: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DEBUG),
     },
+    unsafe_disableDevelopmentModeConsoleWarning:
+      paramUnsafeDisableDevelopmentModeConsoleWarning ??
+      isTruthy(import.meta.env.PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING),
     // Read from params (server-injected via __CLERK_ASTRO_SAFE_VARS__)
     // These are dynamically resolved by middleware, not from env vars
     __internal_keylessClaimUrl: internalOptions?.keylessClaimUrl,

packages/nuxt/src/module.ts

@@ -71,6 +71,8 @@ export default defineNuxtModule<ModuleOptions>({
           // prefetchUI config: can be false or undefined
           prefetchUI: options.prefetchUI,
           isSatellite: options.isSatellite,
+          // Listed explicitly so it can be overridden via NUXT_PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING.
+          unsafe_disableDevelopmentModeConsoleWarning: options.unsafe_disableDevelopmentModeConsoleWarning,
           // Backend specific variables that are safe to share.
           // We want them to be overridable like the other public keys (e.g NUXT_PUBLIC_CLERK_PROXY_URL)
           proxyUrl: options.proxyUrl,

packages/react-router/src/client/ReactRouterClerkProvider.tsx

@@ -67,6 +67,7 @@ function ClerkProviderBase<TUi extends Ui = Ui>({ children, ...rest }: ClerkProv
     __prefetchUI,
     __telemetryDisabled,
     __telemetryDebug,
+    __unsafeDisableDevelopmentModeConsoleWarning,
     __keylessClaimUrl,
     __keylessApiKeysUrl,
   } = clerkState?.__internal_clerk_state || {};
@@ -101,6 +102,7 @@ function ClerkProviderBase<TUi extends Ui = Ui>({ children, ...rest }: ClerkProv
       disabled: __telemetryDisabled,
       debug: __telemetryDebug,
     },
+    unsafe_disableDevelopmentModeConsoleWarning: __unsafeDisableDevelopmentModeConsoleWarning,
   };
 
   const keylessProps = __keylessClaimUrl

packages/react-router/src/client/types.ts

@@ -25,6 +25,7 @@ export type ClerkState = {
     __prefetchUI: boolean | undefined;
     __telemetryDisabled: boolean | undefined;
     __telemetryDebug: boolean | undefined;
+    __unsafeDisableDevelopmentModeConsoleWarning: boolean | undefined;
     __keylessClaimUrl?: string;
     __keylessApiKeysUrl?: string;
   };

packages/react-router/src/server/utils.ts

@@ -102,6 +102,7 @@ export function getResponseClerkState(requestState: RequestStateWithRedirectUrls
     __prefetchUI: envVars.prefetchUI,
     __telemetryDisabled: envVars.telemetryDisabled,
     __telemetryDebug: envVars.telemetryDebug,
+    __unsafeDisableDevelopmentModeConsoleWarning: envVars.unsafeDisableDevelopmentModeConsoleWarning,
   };
 
   if (canUseKeyless && __keylessClaimUrl) {

packages/react-router/src/utils/env.ts

@@ -21,6 +21,9 @@ export const getPublicEnvVariables = (context: AppLoadContext | undefined) => {
     prefetchUI: getValue('CLERK_PREFETCH_UI') === 'false' ? false : undefined,
     telemetryDisabled: isTruthy(getValue('CLERK_TELEMETRY_DISABLED')),
     telemetryDebug: isTruthy(getValue('CLERK_TELEMETRY_DEBUG')),
+    unsafeDisableDevelopmentModeConsoleWarning: isTruthy(
+      getValue('CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING'),
+    ),
     signInForceRedirectUrl: getValue('CLERK_SIGN_IN_FORCE_REDIRECT_URL'),
     signUpForceRedirectUrl: getValue('CLERK_SIGN_UP_FORCE_REDIRECT_URL'),
     signInFallbackRedirectUrl: getValue('CLERK_SIGN_IN_FALLBACK_REDIRECT_URL'),

packages/shared/src/types/clerk.ts

@@ -1123,7 +1123,17 @@ type ClerkOptionsNavigation =
 
 type ClerkUnsafeOptions = {
   /**
-   * Disables the console warning that is logged when Clerk is initialized with development keys.
+   * Disables the `Clerk has been loaded with development keys` console warning that is logged when Clerk is
+   * initialized with development keys. The warning is emitted by `clerk-js` to the browser console; in dev servers
+   * that mirror browser logs to the terminal (e.g. Next.js with `experimental.browserDebugInfoInTerminal`), setting
+   * this option also stops it from showing up there.
+   *
+   * Each framework integration also exposes an env-var shortcut so you don't need to thread the option through
+   * `<ClerkProvider>` manually:
+   * - Next.js: `NEXT_PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`
+   * - Astro: `PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`
+   * - TanStack Start / React Router: `VITE_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`
+   * - Nuxt: `NUXT_PUBLIC_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING`
    *
    * [WARNING] The development mode warning is intended to ensure that you don't go to production with a non-production
    * Clerk instance. If you're disabling it, please make sure you don't ship with a non-production Clerk instance!

packages/tanstack-react-start/src/__tests__/unsafeDisableDevelopmentModeConsoleWarning.test.ts

@@ -0,0 +1,42 @@
+import type { RequestState } from '@clerk/backend/internal';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { mergeWithPublicEnvs, pickFromClerkInitState } from '../client/utils';
+import { getResponseClerkState } from '../server/utils';
+
+const createRequestState = (): RequestState =>
+  ({
+    domain: undefined,
+    isSatellite: false,
+    publishableKey: 'pk_test_xxx',
+    proxyUrl: undefined,
+    signInUrl: undefined,
+    signUpUrl: undefined,
+    toAuth: () => ({}),
+  }) as RequestState;
+
+describe('unsafe_disableDevelopmentModeConsoleWarning', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('preserves an explicit false from the initial state when public env is true', () => {
+    vi.stubEnv('VITE_CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING', 'true');
+
+    const result = mergeWithPublicEnvs({
+      unsafe_disableDevelopmentModeConsoleWarning: false,
+    });
+
+    expect(result.unsafe_disableDevelopmentModeConsoleWarning).toBe(false);
+  });
+
+  it('hydrates the unprefixed env value from server state', () => {
+    vi.stubEnv('CLERK_UNSAFE_DISABLE_DEVELOPMENT_MODE_CONSOLE_WARNING', 'true');
+
+    const clerkInitialState = getResponseClerkState(createRequestState());
+    const pickedState = pickFromClerkInitState(clerkInitialState.__internal_clerk_state);
+    const result = mergeWithPublicEnvs(pickedState);
+
+    expect(result.unsafe_disableDevelopmentModeConsoleWarning).toBe(true);
+  });
+});