initial review

Author: brkalow

packages/nextjs/src/app-router/keyless-actions.ts

@@ -43,7 +43,6 @@ export async function syncKeylessConfigAction(args: AccountlessApplication & { r
      * Force middleware to execute to read the new keys from the cookies and populate the authentication state correctly.
      */
     redirect(`/clerk-sync-keyless?returnUrl=${returnUrl}`, RedirectType.replace);
-    return;
   }
 
   return;

packages/shared/src/__tests__/keyless.spec.ts

@@ -24,14 +24,15 @@ export const clerkMiddleware = (options?: ClerkMiddlewareOptions): AnyRequestMid
 
     // In keyless mode, try to read/create keys from the file system
     if (canUseKeyless && (!publishableKey || !secretKey)) {
-      const keylessApp = await keyless.getOrCreateKeys();
+      const keylessService = keyless();
+      const keylessApp = await keylessService.getOrCreateKeys();
       if (keylessApp) {
         publishableKey = publishableKey || keylessApp.publishableKey;
         secretKey = secretKey || keylessApp.secretKey;
         keylessClaimUrl = keylessApp.claimUrl;
         keylessApiKeysUrl = keylessApp.apiKeysUrl;
 
-        keyless.logKeylessMessage(keylessApp.claimUrl);
+        keylessService.logKeylessMessage(keylessApp.claimUrl);
       }
     }
 

packages/tanstack-react-start/src/server/clerkMiddleware.ts

@@ -76,7 +76,11 @@ export function createFileStorage(options: FileStorageOptions = {}): KeylessStor
   };
 
   const writeReadme = () => {
-    fs.writeFileSync(getReadmePath(), `## DO NOT COMMIT\nThis directory contains keyless mode secrets.\n`, {
+    const readme = `## DO NOT COMMIT
+This directory is auto-generated from \`@clerk/tanstack-react-start\` because you are running in Keyless mode.
+Avoid committing the \`.clerk/\` directory as it includes the secret key of the unclaimed instance.
+`;
+    fs.writeFileSync(getReadmePath(), readme, {
       encoding: 'utf8',
       mode: 0o600,
     });

packages/tanstack-react-start/src/server/keyless/fileStorage.ts

@@ -3,20 +3,35 @@ import { createKeylessService } from '@clerk/shared/keyless';
 import { clerkClient } from '../clerkClient';
 import { createFileStorage } from './fileStorage';
 
-// Create a singleton keyless service for TanStack Start
-export const keyless = createKeylessService({
-  storage: createFileStorage(),
-  api: {
-    createAccountlessApplication: async (requestHeaders?: Headers) => {
-      return await clerkClient().__experimental_accountlessApplications.createAccountlessApplication({
-        requestHeaders,
-      });
-    },
-    completeOnboarding: async (requestHeaders?: Headers) => {
-      return await clerkClient().__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
-        requestHeaders,
-      });
-    },
-  },
-  framework: 'tanstack-react-start',
-});
+// Lazily initialized keyless service singleton
+let keylessServiceInstance: ReturnType<typeof createKeylessService> | null = null;
+
+export function keyless() {
+  if (!keylessServiceInstance) {
+    keylessServiceInstance = createKeylessService({
+      storage: createFileStorage(),
+      api: {
+        async createAccountlessApplication(requestHeaders?: Headers) {
+          try {
+            return await clerkClient().__experimental_accountlessApplications.createAccountlessApplication({
+              requestHeaders,
+            });
+          } catch {
+            return null;
+          }
+        },
+        async completeOnboarding(requestHeaders?: Headers) {
+          try {
+            return await clerkClient().__experimental_accountlessApplications.completeAccountlessApplicationOnboarding({
+              requestHeaders,
+            });
+          } catch {
+            return null;
+          }
+        },
+      },
+      framework: 'tanstack-react-start',
+    });
+  }
+  return keylessServiceInstance;
+}