feat(nextjs): throw missing-env error instead of keyless bootstrap

.changeset/keyless-bootstrap-state-deprecated.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Mark the internal `createBootstrapSignedOutState` as deprecated. It is no longer used by `@clerk/nextjs` and is kept only for older published SDK versions.

.changeset/keyless-cli-init-error.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': minor
+---
+
+In development, missing Clerk keys no longer activate keyless mode. When `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` 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 `.env.local`. Keyless credentials stored in the development keyless cookie are no longer read. Existing apps with configured or claimed keys are unaffected.

integration/models/application.ts

@@ -105,7 +105,15 @@ export const application = (
         await run('pnpm list @clerk/* --depth 100', { cwd: appDirPath, log: clerkPackagesLog });
       }
     },
-    dev: async (opts: { port?: number; manualStart?: boolean; detached?: boolean; serverUrl?: string } = {}) => {
+    dev: async (
+      opts: {
+        port?: number;
+        manualStart?: boolean;
+        detached?: boolean;
+        serverUrl?: string;
+        acceptAnyResponse?: boolean;
+      } = {},
+    ) => {
       const log = logger.child({ prefix: 'dev' }).info;
       const port = opts.port || (await getPort());
       const runtimeServerUrl = resolveServerUrl(opts.serverUrl, serverUrl, port);
@@ -129,7 +137,12 @@ export const application = (
       });
 
       const shouldExit = () => !!proc.exitCode && proc.exitCode !== 0;
-      await waitForServer(runtimeServerUrl, { log, maxAttempts: Infinity, shouldExit });
+      await waitForServer(runtimeServerUrl, {
+        log,
+        maxAttempts: Infinity,
+        shouldExit,
+        acceptAnyResponse: opts.acceptAnyResponse,
+      });
       log(`Server started at ${runtimeServerUrl}, pid: ${proc.pid}`);
       cleanupFns.push(() => awaitableTreekill(proc.pid, 'SIGKILL'));
       state.serverUrl = runtimeServerUrl;

integration/scripts/waitForServer.ts

@@ -3,11 +3,12 @@ type WaitForServerArgsType = {
   delayInMs?: number;
   maxAttempts?: number;
   shouldExit?: () => boolean;
+  acceptAnyResponse?: boolean;
 };
 
 // Poll a url until it returns a 200 status code
 export const waitForServer = async (url: string, opts: WaitForServerArgsType) => {
-  const { log, delayInMs = 1000, maxAttempts = 20, shouldExit = () => false } = opts;
+  const { log, delayInMs = 1000, maxAttempts = 20, shouldExit = () => false, acceptAnyResponse = false } = opts;
   let attempts = 0;
   while (attempts < maxAttempts) {
     if (shouldExit()) {
@@ -17,7 +18,7 @@ export const waitForServer = async (url: string, opts: WaitForServerArgsType) =>
     try {
       log(`Polling ${url}...`);
       const res = await fetch(url);
-      if (res.ok) {
+      if (res.ok || acceptAnyResponse) {
         return Promise.resolve();
       }
     } catch {

integration/tests/next-middleware-keyless.test.ts

@@ -20,16 +20,19 @@ test.describe('Keyless mode | middleware authorization @nextjs', () => {
     app = await commonSetup.commit();
     await app.setup();
     await app.withEnv(appConfigs.envs.withKeyless);
-    await app.dev();
+    // Without keys the app 500s on every request, so readiness can't wait for a 2xx
+    await app.dev({ acceptAnyResponse: true });
   });
 
   test.afterAll(async () => {
     await app.teardown();
   });
 
-  test('auth.protect() in middleware redirects to sign-in during keyless bootstrap', async ({ page }) => {
-    await page.goto(`${app.serverUrl}/protected`);
-    await page.waitForURL(/\/sign-in/);
-    await expect(page.getByTestId('protected')).not.toBeVisible();
+  test('requests without keys fail with the missing env vars error instead of keyless bootstrap', async ({ page }) => {
+    const response = await page.goto(`${app.serverUrl}/protected`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('Missing publishableKey');
+    expect(content).toContain('npx clerk@latest init');
   });
 });

integration/tests/next-quickstart-keyless.test.ts

@@ -1,9 +1,12 @@
+import * as path from 'node:path';
+
 import { expect, test } from '@playwright/test';
 
 import type { Application } from '../models/application';
 import { appConfigs } from '../presets';
+import { fs } from '../scripts';
 import { createTestUtils } from '../testUtils';
-import { mockClaimedInstanceEnvironmentCall, testToggleCollapsePopoverAndClaim } from '../testUtils/keylessHelpers';
+import { mockClaimedInstanceEnvironmentCall } from '../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.next.appRouterQuickstart.clone();
 
@@ -17,87 +20,57 @@ test.describe('Keyless mode @quickstart', () => {
   });
 
   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();
+    // Without keys the app 500s on every request, so readiness can't wait for a 2xx
+    await app.dev({ acceptAnyResponse: true });
   });
 
   test.afterAll(async () => {
     await app.teardown();
   });
 
-  test('Navigates to non-existent page (/_not-found) without a infinite redirect loop.', async ({ page, context }) => {
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-    await u.page.waitForClerkJsLoaded();
-    await u.po.expect.toBeSignedOut();
-
-    await u.po.keylessPopover.waitForMounted();
-
-    const redirectMap = new Map<string, number>();
-    page.on('request', request => {
-      // Only count GET requests since Next.js server actions are sent with POST requests.
-      if (request.method() === 'GET') {
-        const url = request.url();
-        redirectMap.set(url, (redirectMap.get(url) || 0) + 1);
-        expect(redirectMap.get(url)).toBeLessThanOrEqual(1);
-      }
-    });
-
-    await u.page.goToRelative('/something');
-    await u.page.waitForAppUrl('/something');
-  });
-
-  test('Toggle collapse popover and claim.', async ({ page, context }) => {
-    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl, framework: 'nextjs' });
-  });
-
-  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 mockClaimedInstanceEnvironmentCall(page);
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-    await u.page.waitForClerkJsLoaded();
-
-    await u.po.keylessPopover.waitForMounted();
-    expect(await u.po.keylessPopover.isExpanded()).toBe(true);
-    await expect(u.po.keylessPopover.promptToUseClaimedKeys()).toBeVisible();
-
-    const href = await u.po.keylessPopover.promptToUseClaimedKeys().getAttribute('href');
-    expect(href).toBeTruthy();
-    expect(href).toContain(dashboardUrl);
+    const response = await page.goto(`${app.serverUrl}/`);
+    expect(response?.status()).toBe(500);
+    const content = await page.content();
+    expect(content).toContain('Missing publishableKey');
+    expect(content).toContain('npx clerk@latest init');
   });
 
-  test('Claimed application with keys inside .env, on dismiss, keyless prompt is removed.', async ({
+  test('Claimed application with keys inside .env mounts the keyless prompt; on dismiss, it is removed.', async ({
     page,
     context,
   }) => {
-    await mockClaimedInstanceEnvironmentCall(page);
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-
-    await u.po.keylessPopover.waitForMounted();
-    await expect(await u.po.keylessPopover.promptToUseClaimedKeys()).toBeVisible();
-
     /**
-     * Copy keys from `.clerk/.tmp/keyless.json to `.env`
+     * Seed claimed keyless state directly: the SDK no longer mints keys, so write the
+     * keys fixture to `.clerk/.tmp/keyless.json` and copy the matching keys into `.env`.
      */
+    const publishableKey = appConfigs.envs.withEmailCodes.publicVariables.get('CLERK_PUBLISHABLE_KEY');
+    const secretKey = appConfigs.envs.withEmailCodes.privateVariables.get('CLERK_SECRET_KEY');
+    await fs.ensureDir(path.join(app.appDir, '.clerk', '.tmp'));
+    await fs.writeJSON(path.join(app.appDir, '.clerk', '.tmp', 'keyless.json'), {
+      publishableKey,
+      secretKey,
+      claimUrl: 'https://dashboard.clerk.com/apps/claim',
+      apiKeysUrl: 'https://dashboard.clerk.com/last-active?path=api-keys',
+    });
     await app.keylessToEnv();
     /**
      * wait a bit for the server to load the new env file
      */
     await page.waitForTimeout(5_000);
 
-    await page.reload();
+    await mockClaimedInstanceEnvironmentCall(page);
+    const u = createTestUtils({ app, page, context });
+    await u.page.goToAppHome();
+    await u.page.waitForClerkJsLoaded();
+
     await u.po.keylessPopover.waitForMounted();
     await u.po.keylessPopover.promptToDismiss().click();
 

packages/backend/src/tokens/authStatus.ts

@@ -291,6 +291,8 @@ type BootstrapSignedOutParams = {
  * `isSatellite` / `domain` / `proxyUrl` are carried through so that cross-origin
  * satellite redirects produced by `createRedirect` include the `__clerk_status=needs-sync`
  * marker required for the return-trip handshake.
+ *
+ * @deprecated No longer used by `@clerk/nextjs`; kept for older published SDK versions. Will be removed in the next major version.
  */
 export function createBootstrapSignedOutState({
   signInUrl = '',

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,12 +1,12 @@
 'use client';
 import { InternalClerkProvider as ReactClerkProvider, type Ui } from '@clerk/react/internal';
 import { InitialStateProvider } from '@clerk/shared/react';
-import dynamic from 'next/dynamic';
 import { useRouter } from 'next/navigation';
 import React from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
 import { ClerkNextOptionsProvider, useClerkNextOptions } from '../../client-boundary/NextOptionsContext';
+import { errorThrower } from '../../server/errorThrower';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -16,14 +16,6 @@ import { ClerkScripts } from './ClerkScripts';
 import { useAwaitablePush } from './useAwaitablePush';
 import { useAwaitableReplace } from './useAwaitableReplace';
 
-/**
- * LazyCreateKeylessApplication should only be loaded if the conditions below are met.
- * Note: Using lazy() with Suspense instead of dynamic is not possible as React will throw a hydration error when `ClerkProvider` wraps `<html><body>...`
- */
-const LazyCreateKeylessApplication = dynamic(() =>
-  import('./keyless-creator-reader.js').then(m => m.KeylessCreatorOrReader),
-);
-
 const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderProps<TUi>) => {
   const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_scriptsSlot, children } = props;
   const router = useRouter();
@@ -115,9 +107,5 @@ export const ClientClerkProvider = <TUi extends Ui = Ui>(
     return <NextClientClerkProvider {...rest}>{children}</NextClientClerkProvider>;
   }
 
-  return (
-    <LazyCreateKeylessApplication>
-      <NextClientClerkProvider {...rest}>{children}</NextClientClerkProvider>
-    </LazyCreateKeylessApplication>
-  );
+  return errorThrower.throwMissingPublishableKeyError();
 };