feat(*): remove keyless bootstrap from astro, nuxt, react-router, and tanstack-react-start

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: djgould

.changeset/keyless-removal-sweep.md

@@ -0,0 +1,8 @@
+---
+'@clerk/astro': minor
+'@clerk/nuxt': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+---
+
+In development, missing Clerk keys no longer activate keyless mode. When the framework's publishable/secret key environment variables are not set, the SDK now throws an error directing you to run `npx clerk@latest init`, which provisions a Clerk application and writes the keys to your env file. Existing apps with configured keys are unaffected.

integration/tests/astro/keyless.test.ts

@@ -1,12 +1,7 @@
-import { test } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 
 import type { Application } from '../../models/application';
 import { appConfigs } from '../../presets';
-import {
-  testClaimedAppWithMissingKeys,
-  testKeylessRemovedAfterEnvAndRestart,
-  testToggleCollapsePopoverAndClaim,
-} from '../../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.astro.node.clone();
 
@@ -21,34 +16,25 @@ test.describe('Keyless mode @astro', () => {
   });
 
   let app: Application;
-  let dashboardUrl = 'https://dashboard.clerk.com/';
 
   test.beforeAll(async () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    if (appConfigs.envs.withKeyless.privateVariables.get('CLERK_API_URL')?.includes('clerkstage')) {
-      dashboardUrl = 'https://dashboard.clerkstage.dev/';
-    }
     await app.dev();
   });
 
   test.afterAll(async () => {
     await app?.teardown();
   });
 
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'astro' });
-  });
-
-  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+  test('Without keys, the app fails with the missing env vars error instead of keyless bootstrap.', async ({
     page,
-    context,
   }) => {
-    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
-  });
-
-  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
-    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('Publishable key is missing');
+    expect(content).toContain('npx clerk@latest init');
   });
 });

integration/tests/nuxt/keyless.test.ts

@@ -1,12 +1,7 @@
-import { test } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 
 import type { Application } from '../../models/application';
 import { appConfigs } from '../../presets';
-import {
-  testClaimedAppWithMissingKeys,
-  testKeylessRemovedAfterEnvAndRestart,
-  testToggleCollapsePopoverAndClaim,
-} from '../../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.nuxt.node.clone();
 
@@ -21,35 +16,25 @@ test.describe('Keyless mode @nuxt', () => {
   });
 
   let app: Application;
-  let dashboardUrl = 'https://dashboard.clerk.com/';
 
   test.beforeAll(async () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    if (appConfigs.envs.withKeyless.privateVariables.get('CLERK_API_URL')?.includes('clerkstage')) {
-      dashboardUrl = 'https://dashboard.clerkstage.dev/';
-    }
     await app.dev();
   });
 
   test.afterAll(async () => {
-    // Keep files for debugging
     await app?.teardown();
   });
 
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'nuxt' });
-  });
-
-  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+  test('Without keys, the app fails with the missing env vars error instead of keyless bootstrap.', async ({
     page,
-    context,
   }) => {
-    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
-  });
-
-  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
-    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('Publishable key is missing');
+    expect(content).toContain('npx clerk@latest init');
   });
 });

integration/tests/react-router/keyless.test.ts

@@ -1,12 +1,7 @@
-import { test } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 
 import type { Application } from '../../models/application';
 import { appConfigs } from '../../presets';
-import {
-  testClaimedAppWithMissingKeys,
-  testKeylessRemovedAfterEnvAndRestart,
-  testToggleCollapsePopoverAndClaim,
-} from '../../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.reactRouter.reactRouterNode.clone();
 
@@ -21,35 +16,25 @@ test.describe('Keyless mode @react-router', () => {
   });
 
   let app: Application;
-  let dashboardUrl = 'https://dashboard.clerk.com/';
 
   test.beforeAll(async () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    if (appConfigs.envs.withKeyless.privateVariables.get('CLERK_API_URL')?.includes('clerkstage')) {
-      dashboardUrl = 'https://dashboard.clerkstage.dev/';
-    }
     await app.dev();
   });
 
   test.afterAll(async () => {
-    // Keep files for debugging
     await app?.teardown();
   });
 
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'react-router' });
-  });
-
-  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+  test('Without keys, the app fails with the missing env vars error instead of keyless bootstrap.', async ({
     page,
-    context,
   }) => {
-    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
-  });
-
-  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
-    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('A secretKey must be provided');
+    expect(content).toContain('npx clerk@latest init');
   });
 });

integration/tests/tanstack-start/keyless.test.ts

@@ -1,16 +1,11 @@
-import { test } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 
 import type { Application } from '../../models/application';
 import { appConfigs } from '../../presets';
-import {
-  testClaimedAppWithMissingKeys,
-  testKeylessRemovedAfterEnvAndRestart,
-  testToggleCollapsePopoverAndClaim,
-} from '../../testUtils/keylessHelpers';
 
-const commonSetup = appConfigs.reactRouter.reactRouterNode.clone();
+const commonSetup = appConfigs.tanstack.reactStart.clone();
 
-test.describe('Keyless mode @react-router', () => {
+test.describe('Keyless mode @tanstack-react-start', () => {
   test.describe.configure({ mode: 'serial' });
   test.setTimeout(90_000);
 
@@ -21,35 +16,25 @@ test.describe('Keyless mode @react-router', () => {
   });
 
   let app: Application;
-  let dashboardUrl = 'https://dashboard.clerk.com/';
 
   test.beforeAll(async () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    if (appConfigs.envs.withKeyless.privateVariables.get('CLERK_API_URL')?.includes('clerkstage')) {
-      dashboardUrl = 'https://dashboard.clerkstage.dev/';
-    }
     await app.dev();
   });
 
   test.afterAll(async () => {
-    // Keep files for debugging
     await app?.teardown();
   });
 
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'react-router' });
-  });
-
-  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', async ({
+  test('Without keys, the app fails with the missing env vars error instead of keyless bootstrap.', async ({
     page,
-    context,
   }) => {
-    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
-  });
-
-  test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
-    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('no secret key provided');
+    expect(content).toContain('npx clerk@latest init');
   });
 });

packages/astro/src/env.d.ts

@@ -31,9 +31,6 @@ interface ImportMeta {
 declare namespace App {
   interface Locals {
     runtime?: { env: InternalEnv };
-    keylessClaimUrl?: string;
-    keylessApiKeysUrl?: string;
-    keylessPublishableKey?: string;
   }
 }
 

packages/astro/src/internal/create-clerk-instance.ts

@@ -9,7 +9,7 @@ import type { Ui } from '@clerk/ui/internal';
 
 import { $clerkStore } from '../stores/external';
 import { $clerk, $csrState } from '../stores/internal';
-import type { AstroClerkCreateInstanceParams, AstroClerkUpdateOptions, InternalRuntimeOptions } from '../types';
+import type { AstroClerkCreateInstanceParams, AstroClerkUpdateOptions } from '../types';
 import { invokeClerkAstroJSFunctions } from './invoke-clerk-astro-js-functions';
 import { mountAllClerkAstroJSComponents } from './mount-clerk-astro-js-components';
 import { runOnce } from './run-once';
@@ -54,18 +54,12 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
     $clerk.set(clerkJSInstance);
   }
 
-  const internalOptions = options as AstroClerkCreateInstanceParams<TUi> & InternalRuntimeOptions;
-  const keylessClaimUrl = internalOptions.__internal_keylessClaimUrl;
-  const keylessApiKeysUrl = internalOptions.__internal_keylessApiKeysUrl;
-
   const clerkOptions = {
     routerPush: createNavigationHandler(window.history.pushState.bind(window.history)),
     routerReplace: createNavigationHandler(window.history.replaceState.bind(window.history)),
     ...options,
     // Pass the clerk-ui constructor promise to clerk.load()
     ui: { ...options?.ui, ClerkUI },
-    ...(keylessClaimUrl && { __internal_keyless_claimKeylessApplicationUrl: keylessClaimUrl }),
-    ...(keylessApiKeysUrl && { __internal_keyless_copyInstanceKeysUrl: keylessApiKeysUrl }),
   } as unknown as ClerkOptions;
 
   initOptions = clerkOptions;

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

@@ -54,7 +54,6 @@ const mergeEnvVarsWithParams = (
     isSatellite: paramSatellite || import.meta.env.PUBLIC_CLERK_IS_SATELLITE,
     proxyUrl: paramProxy || import.meta.env.PUBLIC_CLERK_PROXY_URL,
     domain: paramDomain || import.meta.env.PUBLIC_CLERK_DOMAIN,
-    // In keyless mode, use server-injected publishableKey from params
     publishableKey:
       paramPublishableKey || internalOptions?.publishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
     __internal_clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
@@ -69,10 +68,6 @@ const mergeEnvVarsWithParams = (
     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,
-    __internal_keylessApiKeysUrl: internalOptions?.keylessApiKeysUrl,
     ...rest,
   };
 };

packages/astro/src/server/__tests__/get-safe-env.test.ts

@@ -211,20 +211,6 @@ describe('getSafeEnv', () => {
     expect(env.pk).toBeUndefined();
     expect(env.sk).toBeUndefined();
   });
-
-  it('prefers keylessPublishableKey over all env sources', () => {
-    process.env.PUBLIC_CLERK_PUBLISHABLE_KEY = 'pk_from_process';
-
-    const locals = createLocals({
-      runtime: { env: undefined as unknown as InternalEnv },
-      keylessPublishableKey: 'pk_keyless',
-    });
-    const env = getSafeEnv(locals);
-
-    expect(env.pk).toBe('pk_keyless');
-
-    delete process.env.PUBLIC_CLERK_PUBLISHABLE_KEY;
-  });
 });
 
 describe('getClientSafeEnv', () => {

packages/astro/src/server/clerk-middleware.ts

@@ -27,12 +27,10 @@ import type { APIContext } from 'astro';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { canUseKeyless } from '../utils/feature-flags';
 import { buildClerkHotloadScript } from './build-clerk-hotload-script';
 import { clerkClient } from './clerk-client';
 import { createCurrentUser } from './current-user';
 import { getClientSafeEnv, getSafeEnv, initCloudflareEnv } from './get-safe-env';
-import { resolveKeysWithKeylessFallback } from './keyless/utils';
 import { serverRedirectWithAuth } from './server-redirect-with-auth';
 import type {
   AstroMiddleware,
@@ -87,42 +85,9 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
     const patchedRequest = patchRequest(context.request);
     const clerkRequest = createClerkRequest(patchedRequest);
 
-    // Resolve keyless URLs per-request in development
-    let keylessClaimUrl: string | undefined;
-    let keylessApiKeysUrl: string | undefined;
-    let keylessOptions = options;
-
-    if (canUseKeyless) {
-      try {
-        const env = getSafeEnv(context);
-        const configuredPublishableKey = options?.publishableKey || env.pk;
-        const configuredSecretKey = options?.secretKey || env.sk;
-
-        const keylessResult = await resolveKeysWithKeylessFallback(
-          configuredPublishableKey,
-          configuredSecretKey,
-          context,
-        );
-
-        keylessClaimUrl = keylessResult.claimUrl;
-        keylessApiKeysUrl = keylessResult.apiKeysUrl;
-
-        // Override keys with keyless values if returned
-        if (keylessResult.publishableKey || keylessResult.secretKey) {
-          keylessOptions = {
-            ...options,
-            ...(keylessResult.publishableKey && { publishableKey: keylessResult.publishableKey }),
-            ...(keylessResult.secretKey && { secretKey: keylessResult.secretKey }),
-          };
-        }
-      } catch {
-        // Silently fail - continue without keyless
-      }
-    }
-
     const requestState = await clerkClient(context).authenticateRequest(
       clerkRequest,
-      createAuthenticateRequestOptions(clerkRequest, keylessOptions, context),
+      createAuthenticateRequestOptions(clerkRequest, options, context),
     );
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
@@ -145,16 +110,6 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
 
     decorateAstroLocal(clerkRequest, authObjectFn, context, requestState);
 
-    // Store keyless data for injection into client
-    if (keylessClaimUrl || keylessApiKeysUrl) {
-      context.locals.keylessClaimUrl = keylessClaimUrl;
-      context.locals.keylessApiKeysUrl = keylessApiKeysUrl;
-      // Also store the resolved publishable key so client can use it
-      if (keylessOptions?.publishableKey) {
-        context.locals.keylessPublishableKey = keylessOptions.publishableKey;
-      }
-    }
-
     /**
      * ALS is crucial for guaranteeing SSR in UI frameworks like React.
      * This currently powers the `useAuth()` React hook and any other hook or Component that depends on it.