feat(nuxt): Add support for keyless mode

.changeset/lazy-turkeys-switch.md

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

.changeset/tiny-papayas-hope.md

@@ -0,0 +1,6 @@
+---
+"@clerk/astro": patch
+"@clerk/react-router": patch
+---
+
+Simplified keyless service initialization.

integration/templates/nuxt-node/package.json

@@ -10,8 +10,8 @@
     "preview": "nuxt preview --port $PORT"
   },
   "dependencies": {
-    "nuxt": "4.1.2",
-    "vue": "^3.5.13",
-    "vue-router": "^4.4.5"
+    "nuxt": "4.4.2",
+    "vue": "^3.5.30",
+    "vue-router": "^5.0.3"
   }
 }

integration/tests/nuxt/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.nuxt.node.clone();
+
+test.describe('Keyless mode @nuxt', () => {
+  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, framework: 'nuxt' });
+  });
+
+  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/src/server/keyless/index.ts

@@ -4,83 +4,37 @@ import type { APIContext } from 'astro';
 import { clerkClient } from '../clerk-client';
 import { createFileStorage } from './file-storage.js';
 
+// Lazily initialized keyless service singleton
 let keylessServiceInstance: ReturnType<typeof createKeylessService> | null = null;
-let keylessInitPromise: Promise<ReturnType<typeof createKeylessService> | null> | null = null;
 
-function canUseFileSystem(): boolean {
-  try {
-    return typeof process !== 'undefined' && typeof process.cwd === 'function';
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Gets or creates the keyless service singleton.
- * Returns null for non-Node.js runtimes (e.g., Cloudflare Workers).
- */
-export async function keyless(context: APIContext): Promise<ReturnType<typeof createKeylessService> | null> {
-  if (!canUseFileSystem()) {
-    return null;
-  }
-
-  if (keylessServiceInstance) {
-    return keylessServiceInstance;
-  }
-
-  if (keylessInitPromise) {
-    return keylessInitPromise;
-  }
-
-  keylessInitPromise = (async () => {
-    try {
-      const storage = await createFileStorage();
-
-      const service = createKeylessService({
-        storage,
-        api: {
-          async createAccountlessApplication(requestHeaders?: Headers) {
-            try {
-              return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
-                requestHeaders,
-              });
-            } catch {
-              return null;
-            }
-          },
-          async completeOnboarding(requestHeaders?: Headers) {
-            try {
-              return await clerkClient(
-                context,
-              ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
-                requestHeaders,
-              });
-            } catch {
-              return null;
-            }
-          },
+export function keyless(context: APIContext) {
+  if (!keylessServiceInstance) {
+    keylessServiceInstance = createKeylessService({
+      storage: createFileStorage(),
+      api: {
+        async createAccountlessApplication(requestHeaders?: Headers) {
+          try {
+            return await clerkClient(context).__experimental_accountlessApplications.createAccountlessApplication({
+              requestHeaders,
+            });
+          } catch {
+            return null;
+          }
         },
-        framework: 'astro',
-        frameworkVersion: PACKAGE_VERSION,
-      });
-
-      keylessServiceInstance = service;
-      return service;
-    } catch (error) {
-      console.warn('[Clerk] Failed to initialize keyless service:', error);
-      return null;
-    } finally {
-      keylessInitPromise = null;
-    }
-  })();
-
-  return keylessInitPromise;
-}
-
-/**
- * @internal
- */
-export function resetKeylessService(): void {
-  keylessServiceInstance = null;
-  keylessInitPromise = null;
+        async completeOnboarding(requestHeaders?: Headers) {
+          try {
+            return await clerkClient(
+              context,
+            ).__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+              requestHeaders,
+            });
+          } catch {
+            return null;
+          }
+        },
+      },
+      framework: 'astro',
+    });
+  }
+  return keylessServiceInstance;
 }

packages/nuxt/src/module.ts

@@ -74,8 +74,10 @@ export default defineNuxtModule<ModuleOptions>({
           // 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,
-          apiUrl: '',
-          apiVersion: 'v1',
+          // Deprecated: use NUXT_CLERK_API_URL and NUXT_CLERK_API_VERSION instead.
+          // Kept for backwards compatibility with NUXT_PUBLIC_CLERK_API_URL / NUXT_PUBLIC_CLERK_API_VERSION.
+          apiUrl: undefined,
+          apiVersion: undefined,
         },
       },
       // Private keys available only on within server-side
@@ -84,6 +86,8 @@ export default defineNuxtModule<ModuleOptions>({
         machineSecretKey: undefined,
         jwtKey: undefined,
         webhookSigningSecret: undefined,
+        apiUrl: undefined,
+        apiVersion: undefined,
       },
     });
 

packages/nuxt/src/runtime/plugin.ts

@@ -4,16 +4,20 @@ import { clerkPlugin } from '@clerk/vue';
 import { setErrorThrowerOptions } from '@clerk/vue/internal';
 import { defineNuxtPlugin, navigateTo, useRuntimeConfig, useState } from 'nuxt/app';
 
+import type { ClerkKeylessContext } from './server/types';
+
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 setClerkJSLoadingErrorPackageName(PACKAGE_NAME);
 
 export default defineNuxtPlugin(nuxtApp => {
   // SSR-friendly shared state
   const initialState = useState<InitialState | undefined>('clerk-initial-state', () => undefined);
+  const keylessContext = useState<ClerkKeylessContext | undefined>('clerk-keyless-context', () => undefined);
 
   if (import.meta.server) {
     // Save the initial state from server and pass it to the plugin
     initialState.value = nuxtApp.ssrContext?.event.context.__clerk_initial_state;
+    keylessContext.value = nuxtApp.ssrContext?.event.context.__clerk_keyless;
   }
 
   const runtimeConfig = useRuntimeConfig();
@@ -34,5 +38,12 @@ export default defineNuxtPlugin(nuxtApp => {
     routerPush: (to: string) => navigateTo(to),
     routerReplace: (to: string) => navigateTo(to, { replace: true }),
     initialState: initialState.value,
+    // Add keyless mode props if present
+    ...(keylessContext.value
+      ? {
+          __internal_keyless_claimKeylessApplicationUrl: keylessContext.value.claimUrl,
+          __internal_keyless_copyInstanceKeysUrl: keylessContext.value.apiKeysUrl,
+        }
+      : {}),
   });
 });

packages/nuxt/src/runtime/server/clerkClient.ts

@@ -1,20 +1,41 @@
 import { createClerkClient } from '@clerk/backend';
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { deprecated } from '@clerk/shared/deprecated';
 import { isTruthy } from '@clerk/shared/underscore';
 import type { H3Event } from 'h3';
 
 // @ts-expect-error: Nitro import. Handled by Nuxt.
 import { useRuntimeConfig } from '#imports';
 
+function resolveApiUrl(runtimeConfig: ReturnType<typeof useRuntimeConfig>): string {
+  if (runtimeConfig.clerk.apiUrl) {
+    return runtimeConfig.clerk.apiUrl;
+  }
+  if (runtimeConfig.public.clerk.apiUrl) {
+    deprecated('NUXT_PUBLIC_CLERK_API_URL', 'Use `NUXT_CLERK_API_URL` instead.');
+    return runtimeConfig.public.clerk.apiUrl;
+  }
+  return apiUrlFromPublishableKey(runtimeConfig.public.clerk.publishableKey);
+}
+
+function resolveApiVersion(runtimeConfig: ReturnType<typeof useRuntimeConfig>): string {
+  if (runtimeConfig.clerk.apiVersion) {
+    return runtimeConfig.clerk.apiVersion;
+  }
+  if (runtimeConfig.public.clerk.apiVersion) {
+    deprecated('NUXT_PUBLIC_CLERK_API_VERSION', 'Use `NUXT_CLERK_API_VERSION` instead.');
+    return runtimeConfig.public.clerk.apiVersion;
+  }
+  return 'v1';
+}
+
 export function clerkClient(event: H3Event) {
   const runtimeConfig = useRuntimeConfig(event);
-  const publishableKey = runtimeConfig.public.clerk.publishableKey;
-  const apiUrl = runtimeConfig.public.clerk.apiUrl || apiUrlFromPublishableKey(publishableKey);
 
   return createClerkClient({
-    publishableKey,
-    apiUrl,
-    apiVersion: runtimeConfig.public.clerk.apiVersion,
+    publishableKey: runtimeConfig.public.clerk.publishableKey,
+    apiUrl: resolveApiUrl(runtimeConfig),
+    apiVersion: resolveApiVersion(runtimeConfig),
     proxyUrl: runtimeConfig.public.clerk.proxyUrl,
     domain: runtimeConfig.public.clerk.domain,
     isSatellite: runtimeConfig.public.clerk.isSatellite,

packages/nuxt/src/runtime/server/clerkMiddleware.ts

@@ -5,7 +5,12 @@ import type { PendingSessionOptions } from '@clerk/shared/types';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
+// @ts-expect-error: Nitro import. Handled by Nuxt.
+import { useRuntimeConfig } from '#imports';
+
+import { canUseKeyless } from '../utils/feature-flags';
 import { clerkClient } from './clerkClient';
+import { resolveKeysWithKeylessFallback } from './keyless/utils';
 import type { AuthFn, AuthOptions } from './types';
 import { createInitialState, toWebRequest } from './utils';
 
@@ -82,6 +87,35 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
   return eventHandler(async event => {
     const clerkRequest = toWebRequest(event);
 
+    // Resolve keyless in development if keys are missing
+    let keylessClaimUrl: string | undefined;
+    let keylessApiKeysUrl: string | undefined;
+
+    if (canUseKeyless) {
+      try {
+        const runtimeConfig = useRuntimeConfig(event);
+
+        const { publishableKey, secretKey, claimUrl, apiKeysUrl } = await resolveKeysWithKeylessFallback(
+          runtimeConfig.public.clerk.publishableKey,
+          runtimeConfig.clerk.secretKey,
+          event,
+        );
+
+        keylessClaimUrl = claimUrl;
+        keylessApiKeysUrl = apiKeysUrl;
+
+        // Override runtime config with keyless values if returned
+        if (publishableKey) {
+          runtimeConfig.public.clerk.publishableKey = publishableKey;
+        }
+        if (secretKey) {
+          runtimeConfig.clerk.secretKey = secretKey;
+        }
+      } catch {
+        // Silently fail - continue without keyless
+      }
+    }
+
     const requestState = await clerkClient(event).authenticateRequest(clerkRequest, {
       ...options,
       acceptsToken: 'any',
@@ -117,6 +151,14 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
     // Internal serializable state that will be passed to the client
     event.context.__clerk_initial_state = createInitialState(authObjectFn());
 
+    // Store keyless mode URLs in separate context property
+    if (canUseKeyless && keylessClaimUrl) {
+      event.context.__clerk_keyless = {
+        claimUrl: keylessClaimUrl,
+        apiKeysUrl: keylessApiKeysUrl,
+      };
+    }
+
     await handler?.(event);
   });
 };

packages/nuxt/src/runtime/server/keyless/fileStorage.ts

@@ -0,0 +1,19 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { createNodeFileStorage, type KeylessStorage } from '@clerk/shared/keyless';
+
+export type { KeylessStorage };
+
+export interface FileStorageOptions {
+  cwd?: () => string;
+}
+
+export function createFileStorage(options: FileStorageOptions = {}): KeylessStorage {
+  const { cwd = () => process.cwd() } = options;
+
+  return createNodeFileStorage(fs, path, {
+    cwd,
+    frameworkPackageName: '@clerk/nuxt',
+  });
+}