feat(react-router): Add support for keyless mode

.changeset/curvy-jobs-pump.md

@@ -0,0 +1,5 @@
+---
+"@clerk/react-router": minor
+---
+
+Introduce Keyless quickstart for React Router. This allows the Clerk SDK to be used without having to sign up and paste your keys manually.

integration/testUtils/keylessHelpers.ts

@@ -0,0 +1,138 @@
+import type { BrowserContext, Page } from '@playwright/test';
+import { expect } from '@playwright/test';
+
+import type { Application } from '../models/application';
+import { createTestUtils } from './index';
+
+/**
+ * Mocks the environment API call to return a claimed instance.
+ * Used in keyless mode tests to simulate an instance that has been claimed.
+ */
+export const mockClaimedInstanceEnvironmentCall = async (page: Page): Promise<void> => {
+  await page.route('*/**/v1/environment*', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    const newJson = {
+      ...json,
+      auth_config: {
+        ...json.auth_config,
+        claimed_at: Date.now(),
+      },
+    };
+    await route.fulfill({ response, json: newJson });
+  });
+};
+
+/**
+ * Tests that the keyless popover can be toggled and the claim link opens the dashboard.
+ */
+export async function testToggleCollapsePopoverAndClaim({
+  page,
+  context,
+  app,
+  dashboardUrl,
+}: {
+  page: Page;
+  context: BrowserContext;
+  app: Application;
+  dashboardUrl: string;
+}): Promise<void> {
+  const u = createTestUtils({ app, page, context });
+  await u.page.goToAppHome();
+  await u.page.waitForClerkJsLoaded();
+  await u.po.expect.toBeSignedOut();
+
+  await u.po.keylessPopover.waitForMounted();
+
+  expect(await u.po.keylessPopover.isExpanded()).toBe(false);
+  await u.po.keylessPopover.toggle();
+  expect(await u.po.keylessPopover.isExpanded()).toBe(true);
+
+  const claim = u.po.keylessPopover.promptsToClaim();
+
+  const [newPage] = await Promise.all([context.waitForEvent('page'), claim.click()]);
+
+  await newPage.waitForLoadState();
+
+  await newPage.waitForURL(url => {
+    const urlToReturnTo = `${dashboardUrl}apps/claim?token=`;
+
+    const signUpForceRedirectUrl = url.searchParams.get('sign_up_force_redirect_url');
+
+    const signUpForceRedirectUrlCheck =
+      signUpForceRedirectUrl?.startsWith(urlToReturnTo) ||
+      (signUpForceRedirectUrl?.startsWith(`${dashboardUrl}prepare-account`) &&
+        signUpForceRedirectUrl?.includes(encodeURIComponent('apps/claim?token=')));
+
+    return (
+      url.pathname === '/apps/claim/sign-in' &&
+      url.searchParams.get('sign_in_force_redirect_url')?.startsWith(urlToReturnTo) &&
+      signUpForceRedirectUrlCheck
+    );
+  });
+}
+
+/**
+ * Tests that a claimed application with missing explicit keys shows the popover expanded
+ * with a prompt to get keys from the dashboard.
+ */
+export async function testClaimedAppWithMissingKeys({
+  page,
+  context,
+  app,
+  dashboardUrl,
+}: {
+  page: Page;
+  context: BrowserContext;
+  app: Application;
+  dashboardUrl: string;
+}): Promise<void> {
+  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 [newPage] = await Promise.all([
+    context.waitForEvent('page'),
+    u.po.keylessPopover.promptToUseClaimedKeys().click(),
+  ]);
+
+  await newPage.waitForLoadState();
+  await newPage.waitForURL(url => {
+    return url.href.startsWith(`${dashboardUrl}sign-in?redirect_url=${encodeURIComponent(dashboardUrl)}apps%2Fapp_`);
+  });
+}
+
+/**
+ * Tests that the keyless popover is removed after adding keys to .env and restarting the dev server.
+ */
+export async function testKeylessRemovedAfterEnvAndRestart({
+  page,
+  context,
+  app,
+}: {
+  page: Page;
+  context: BrowserContext;
+  app: Application;
+}): Promise<void> {
+  const u = createTestUtils({ app, page, context });
+  await u.page.goToAppHome();
+
+  await u.po.keylessPopover.waitForMounted();
+  expect(await u.po.keylessPopover.isExpanded()).toBe(false);
+
+  // Copy keys from keyless.json to .env
+  await app.keylessToEnv();
+
+  // Restart the dev server to pick up new env vars (Vite doesn't hot-reload .env)
+  await app.restart();
+
+  await u.page.goToAppHome();
+
+  // Keyless popover should no longer be present since we now have explicit keys
+  await u.po.keylessPopover.waitForUnmounted();
+}

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

@@ -1,27 +1,12 @@
-import type { Page } from '@playwright/test';
 import { expect, test } from '@playwright/test';
 
 import type { Application } from '../models/application';
 import { appConfigs } from '../presets';
 import { createTestUtils } from '../testUtils';
+import { mockClaimedInstanceEnvironmentCall } from '../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.next.appRouterQuickstart.clone();
 
-const mockClaimedInstanceEnvironmentCall = async (page: Page) => {
-  await page.route('*/**/v1/environment*', async route => {
-    const response = await route.fetch();
-    const json = await response.json();
-    const newJson = {
-      ...json,
-      auth_config: {
-        ...json.auth_config,
-        claimed_at: Date.now(),
-      },
-    };
-    await route.fulfill({ response, json: newJson });
-  });
-};
-
 test.describe('Keyless mode @quickstart', () => {
   test.describe.configure({ mode: 'serial' });
 

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

@@ -0,0 +1,55 @@
+import { 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();
+
+test.describe('Keyless mode @react-router', () => {
+  test.describe.configure({ mode: 'serial' });
+  test.setTimeout(90_000);
+
+  test.use({
+    extraHTTPHeaders: {
+      'x-vercel-protection-bypass': process.env.VERCEL_AUTOMATION_BYPASS_SECRET || '',
+    },
+  });
+
+  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 });
+  });
+
+  test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', 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 });
+  });
+});

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

@@ -1,27 +1,15 @@
-import type { Page } from '@playwright/test';
-import { expect, test } from '@playwright/test';
+import { test } from '@playwright/test';
 
 import type { Application } from '../../models/application';
 import { appConfigs } from '../../presets';
-import { createTestUtils } from '../../testUtils';
+import {
+  testClaimedAppWithMissingKeys,
+  testKeylessRemovedAfterEnvAndRestart,
+  testToggleCollapsePopoverAndClaim,
+} from '../../testUtils/keylessHelpers';
 
 const commonSetup = appConfigs.tanstack.reactStart.clone();
 
-const mockClaimedInstanceEnvironmentCall = async (page: Page) => {
-  await page.route('*/**/v1/environment*', async route => {
-    const response = await route.fetch();
-    const json = await response.json();
-    const newJson = {
-      ...json,
-      auth_config: {
-        ...json.auth_config,
-        claimed_at: Date.now(),
-      },
-    };
-    await route.fulfill({ response, json: newJson });
-  });
-};
-
 test.describe('Keyless mode @tanstack-react-start', () => {
   test.describe.configure({ mode: 'serial' });
   test.setTimeout(90_000);
@@ -51,81 +39,17 @@ test.describe('Keyless mode @tanstack-react-start', () => {
   });
 
   test('Toggle collapse popover and claim.', 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();
-
-    expect(await u.po.keylessPopover.isExpanded()).toBe(false);
-    await u.po.keylessPopover.toggle();
-    expect(await u.po.keylessPopover.isExpanded()).toBe(true);
-
-    const claim = await u.po.keylessPopover.promptsToClaim();
-
-    const [newPage] = await Promise.all([context.waitForEvent('page'), claim.click()]);
-
-    await newPage.waitForLoadState();
-
-    await newPage.waitForURL(url => {
-      const urlToReturnTo = `${dashboardUrl}apps/claim?token=`;
-
-      const signUpForceRedirectUrl = url.searchParams.get('sign_up_force_redirect_url');
-
-      const signUpForceRedirectUrlCheck =
-        signUpForceRedirectUrl?.startsWith(urlToReturnTo) ||
-        (signUpForceRedirectUrl?.startsWith(`${dashboardUrl}prepare-account`) &&
-          signUpForceRedirectUrl?.includes(encodeURIComponent('apps/claim?token=')));
-
-      return (
-        url.pathname === '/apps/claim/sign-in' &&
-        url.searchParams.get('sign_in_force_redirect_url')?.startsWith(urlToReturnTo) &&
-        signUpForceRedirectUrlCheck
-      );
-    });
+    await testToggleCollapsePopoverAndClaim({ page, context, app, dashboardUrl });
   });
 
   test('Lands on claimed application with missing explicit keys, expanded by default, click to get keys from dashboard.', 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 [newPage] = await Promise.all([
-      context.waitForEvent('page'),
-      u.po.keylessPopover.promptToUseClaimedKeys().click(),
-    ]);
-
-    await newPage.waitForLoadState();
-    await newPage.waitForURL(url => {
-      return url.href.startsWith(`${dashboardUrl}sign-in?redirect_url=${encodeURIComponent(dashboardUrl)}apps%2Fapp_`);
-    });
+    await testClaimedAppWithMissingKeys({ page, context, app, dashboardUrl });
   });
 
   test('Keyless popover is removed after adding keys to .env and restarting.', async ({ page, context }) => {
-    const u = createTestUtils({ app, page, context });
-    await u.page.goToAppHome();
-
-    await u.po.keylessPopover.waitForMounted();
-    expect(await u.po.keylessPopover.isExpanded()).toBe(false);
-
-    // Copy keys from keyless.json to .env
-    await app.keylessToEnv();
-
-    // Restart the dev server to pick up new env vars (Vite doesn't hot-reload .env)
-    await app.restart();
-
-    await u.page.goToAppHome();
-
-    // Keyless popover should no longer be present since we now have explicit keys
-    await u.po.keylessPopover.waitForUnmounted();
+    await testKeylessRemovedAfterEnvAndRestart({ page, context, app });
   });
 });

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

@@ -67,6 +67,8 @@ function ClerkProviderBase<TUi extends Ui = Ui>({ children, ...rest }: ClerkProv
     __prefetchUI,
     __telemetryDisabled,
     __telemetryDebug,
+    __keylessClaimUrl,
+    __keylessApiKeysUrl,
   } = clerkState?.__internal_clerk_state || {};
 
   React.useEffect(() => {
@@ -100,6 +102,13 @@ function ClerkProviderBase<TUi extends Ui = Ui>({ children, ...rest }: ClerkProv
     },
   };
 
+  const keylessProps = __keylessClaimUrl
+    ? {
+        __internal_keyless_claimKeylessApplicationUrl: __keylessClaimUrl,
+        __internal_keyless_copyInstanceKeysUrl: __keylessApiKeysUrl,
+      }
+    : {};
+
   return (
     <ClerkReactRouterOptionsProvider options={mergedProps}>
       <ReactClerkProvider
@@ -108,6 +117,7 @@ function ClerkProviderBase<TUi extends Ui = Ui>({ children, ...rest }: ClerkProv
         initialState={__clerk_ssr_state}
         sdkMetadata={SDK_METADATA}
         {...mergedProps}
+        {...keylessProps}
         {...restProps}
       >
         {children}

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

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