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',
+ });
+}

.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',
+ });
+}

.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',
+ });
+}

.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',
+ });
+}

.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',
+ });
+}

.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',
+ });
+}

.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',
+ });
+}