feat(astro): Add support for keyless mode

- Add keyless service with file storage adapter
- Middleware resolves keyless URLs per-request (runtime, not compile-time)
- Store keyless data in context.locals
- Inject keyless URLs via __CLERK_ASTRO_SAFE_VARS__ script tag
- Client reads from params (server-injected) instead of import.meta.env
- Add feature flag for keyless mode
- Add integration test using shared keyless helpers
- Add @clerk/shared as dependency for shared keyless utilities

Follows runtime pattern from React Router and TanStack Start:
- No browser cache issues
- Instant updates when switching modes
- Clean separation: Integration for build, Middleware for runtime

Author: wobsoriano

integration/tests/astro/keyless.test.ts

@@ -0,0 +1,54 @@
+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.astro.node.clone();
+
+test.describe('Keyless mode @astro', () => {
+  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 () => {
+    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 ({
+    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 });
+  });
+});

packages/astro/package.json

@@ -97,7 +97,8 @@
   },
   "devDependencies": {
     "@clerk/ui": "workspace:^",
-    "astro": "^5.15.9"
+    "astro": "^5.15.9",
+    "vite": "^7.1.0"
   },
   "peerDependencies": {
     "astro": "^4.15.0 || ^5.0.0"

packages/astro/src/env.d.ts

@@ -21,6 +21,7 @@ interface InternalEnv {
   readonly PUBLIC_CLERK_SIGN_UP_URL?: string;
   readonly PUBLIC_CLERK_TELEMETRY_DISABLED?: string;
   readonly PUBLIC_CLERK_TELEMETRY_DEBUG?: string;
+  readonly PUBLIC_CLERK_KEYLESS_DISABLED?: string;
 }
 
 interface ImportMeta {
@@ -30,6 +31,9 @@ interface ImportMeta {
 declare namespace App {
   interface Locals {
     runtime: { env: InternalEnv };
+    keylessClaimUrl?: string;
+    keylessApiKeysUrl?: string;
+    keylessPublishableKey?: string;
   }
 }
 

packages/astro/src/integration/create-integration.ts

@@ -28,17 +28,24 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
     return {
       name: '@clerk/astro/integration',
       hooks: {
-        'astro:config:setup': ({ config, injectScript, updateConfig, logger, command }) => {
+        'astro:config:setup': async ({ config, injectScript, updateConfig, logger, command }) => {
           if (['server', 'hybrid'].includes(config.output) && !config.adapter) {
             logger.error('Missing adapter, please update your Astro config to use one.');
           }
 
+          const isDev = command === 'dev';
+
+          // Read keys from process.env for vite.define injection
+          // Note: Keyless mode is now handled by middleware per-request, not here
+          const envPublishableKey = process.env.PUBLIC_CLERK_PUBLISHABLE_KEY;
+          const envSecretKey = process.env.CLERK_SECRET_KEY;
+
           const internalParams: ClerkOptions = {
             ...params,
             sdkMetadata: {
               version: packageVersion,
               name: packageName,
-              environment: command === 'dev' ? 'development' : 'production',
+              environment: isDev ? 'development' : 'production',
             },
           };
 
@@ -64,6 +71,9 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                   prefetchUI === false || hasUI ? 'false' : undefined,
                   'PUBLIC_CLERK_PREFETCH_UI',
                 ),
+                ...buildEnvVarFromOption(envPublishableKey, 'PUBLIC_CLERK_PUBLISHABLE_KEY'),
+                ...buildEnvVarFromOption(envSecretKey, 'CLERK_SECRET_KEY'),
+                // Keyless URLs are now handled by middleware, not vite.define
               },
 
               ssr: {
@@ -166,7 +176,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
 
 function createClerkEnvSchema() {
   return {
-    PUBLIC_CLERK_PUBLISHABLE_KEY: envField.string({ context: 'client', access: 'public' }),
+    PUBLIC_CLERK_PUBLISHABLE_KEY: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_SIGN_IN_URL: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_SIGN_UP_URL: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_IS_SATELLITE: envField.boolean({ context: 'client', access: 'public', optional: true }),
@@ -179,7 +189,20 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_UI_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_TELEMETRY_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_TELEMETRY_DEBUG: envField.boolean({ context: 'client', access: 'public', optional: true }),
-    CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret' }),
+    PUBLIC_CLERK_KEYLESS_CLAIM_URL: envField.string({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      url: true,
+    }),
+    PUBLIC_CLERK_KEYLESS_API_KEYS_URL: envField.string({
+      context: 'client',
+      access: 'public',
+      optional: true,
+      url: true,
+    }),
+    PUBLIC_CLERK_KEYLESS_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
+    CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
     CLERK_MACHINE_SECRET_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
     CLERK_JWT_KEY: envField.string({ context: 'server', access: 'secret', optional: true }),
   };

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

@@ -54,12 +54,17 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
     $clerk.set(clerkJSInstance);
   }
 
+  const keylessClaimUrl = (options as any)?.__internal_keylessClaimUrl;
+  const keylessApiKeysUrl = (options as any)?.__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

@@ -58,6 +58,8 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
       disabled: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DISABLED),
       debug: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DEBUG),
     },
+    __internal_keylessClaimUrl: import.meta.env.PUBLIC_CLERK_KEYLESS_CLAIM_URL,
+    __internal_keylessApiKeysUrl: import.meta.env.PUBLIC_CLERK_KEYLESS_API_KEYS_URL,
     ...rest,
   };
 };

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

@@ -24,10 +24,12 @@ 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 } from './get-safe-env';
+import { resolveKeysWithKeylessFallback } from './keyless/utils';
 import { serverRedirectWithAuth } from './server-redirect-with-auth';
 import type {
   AstroMiddleware,
@@ -79,9 +81,38 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
 
     const clerkRequest = createClerkRequest(context.request);
 
+    // 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);
+
+        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 (error) {
+        // Silently fail - continue without keyless
+      }
+    }
+
     const requestState = await clerkClient(context).authenticateRequest(
       clerkRequest,
-      createAuthenticateRequestOptions(clerkRequest, options, context),
+      createAuthenticateRequestOptions(clerkRequest, keylessOptions, context),
     );
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
@@ -104,6 +135,16 @@ 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.

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

@@ -39,6 +39,8 @@ function getSafeEnv(context: ContextOrLocals) {
     apiUrl: getContextEnvVar('CLERK_API_URL', context),
     telemetryDisabled: isTruthy(getContextEnvVar('PUBLIC_CLERK_TELEMETRY_DISABLED', context)),
     telemetryDebug: isTruthy(getContextEnvVar('PUBLIC_CLERK_TELEMETRY_DEBUG', context)),
+    keylessClaimUrl: getContextEnvVar('PUBLIC_CLERK_KEYLESS_CLAIM_URL', context),
+    keylessApiKeysUrl: getContextEnvVar('PUBLIC_CLERK_KEYLESS_API_KEYS_URL', context),
   };
 }
 
@@ -56,6 +58,8 @@ function getClientSafeEnv(context: ContextOrLocals) {
     proxyUrl: getContextEnvVar('PUBLIC_CLERK_PROXY_URL', context),
     signInUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_IN_URL', context),
     signUpUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_UP_URL', context),
+    keylessClaimUrl: getContextEnvVar('PUBLIC_CLERK_KEYLESS_CLAIM_URL', context),
+    keylessApiKeysUrl: getContextEnvVar('PUBLIC_CLERK_KEYLESS_API_KEYS_URL', context),
   };
 }
 

packages/astro/src/server/keyless/file-storage.ts

@@ -0,0 +1,20 @@
+import type { KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+  cwd?: () => string;
+}
+
+export async function createFileStorage(options: FileStorageOptions = {}): Promise<KeylessStorage> {
+  const { cwd = () => process.cwd() } = options;
+
+  const [{ default: fs }, { default: path }] = await Promise.all([import('node:fs'), import('node:path')]);
+
+  const { createNodeFileStorage } = await import('@clerk/shared/keyless');
+
+  return createNodeFileStorage(fs, path, {
+    cwd,
+    frameworkPackageName: '@clerk/astro',
+  });
+}

packages/astro/src/server/keyless/index.ts

@@ -0,0 +1,50 @@
+import { createClerkClient } from '@clerk/backend';
+import { createKeylessService } from '@clerk/shared/keyless';
+
+import { createFileStorage } from './file-storage.js';
+
+let keylessServiceInstance: ReturnType<typeof createKeylessService> | null = null;
+
+export async function keyless() {
+  if (!keylessServiceInstance) {
+    const storage = await createFileStorage();
+
+    keylessServiceInstance = createKeylessService({
+      storage,
+      api: {
+        async createAccountlessApplication(requestHeaders?: Headers) {
+          try {
+            const client = createClerkClient({
+              secretKey: process.env.CLERK_SECRET_KEY,
+              publishableKey: process.env.PUBLIC_CLERK_PUBLISHABLE_KEY,
+              apiUrl: process.env.CLERK_API_URL,
+            });
+            return await client.__experimental_accountlessApplications.createAccountlessApplication({
+              requestHeaders,
+            });
+          } catch {
+            return null;
+          }
+        },
+        async completeOnboarding(requestHeaders?: Headers) {
+          try {
+            const client = createClerkClient({
+              secretKey: process.env.CLERK_SECRET_KEY,
+              publishableKey: process.env.PUBLIC_CLERK_PUBLISHABLE_KEY,
+              apiUrl: process.env.CLERK_API_URL,
+            });
+            return await client.__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+              requestHeaders,
+            });
+          } catch {
+            return null;
+          }
+        },
+      },
+      framework: 'astro',
+      frameworkVersion: PACKAGE_VERSION,
+    });
+  }
+
+  return keylessServiceInstance;
+}