feat(shared): Improve error handling for clerk-js loading

.changeset/tangy-bees-follow.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': minor
+---
+
+Improve error handling when loading clerk-js.

packages/shared/src/__tests__/loadClerkJsScript.test.ts

@@ -1,3 +1,4 @@
+import { ClerkRuntimeError } from '../error';
 import {
   buildClerkJsScriptAttributes,
   clerkJsScriptUrl,
@@ -86,8 +87,8 @@ describe('loadClerkJsScript(options)', () => {
       rejectedWith = error;
     }
 
-    expect(rejectedWith).toBeInstanceOf(Error);
-    expect(rejectedWith.message).toBe('Clerk: Failed to load Clerk');
+    expect(rejectedWith).toBeInstanceOf(ClerkRuntimeError);
+    expect(rejectedWith.message).toContain('Clerk: Failed to load Clerk');
     expect((window as any).Clerk).toBeUndefined();
   });
 
@@ -137,8 +138,8 @@ describe('loadClerkJsScript(options)', () => {
       await loadPromise;
       fail('Should have thrown error');
     } catch (error) {
-      expect(error).toBeInstanceOf(Error);
-      expect((error as Error).message).toBe('Clerk: Failed to load Clerk');
+      expect(error).toBeInstanceOf(ClerkRuntimeError);
+      expect((error as Error).message).toContain('Clerk: Failed to load Clerk');
       // The malformed Clerk object should still be there since it was set
       expect((window as any).Clerk).toEqual({ status: 'ready' });
     }

packages/shared/src/errors/runtimeError.ts

@@ -18,7 +18,12 @@ export class ClerkRuntimeError extends Error {
    */
   code: string;
 
-  constructor(message: string, { code }: { code: string }) {
+  /**
+   * The original error that was caught to throw an instance of ClerkRuntimeError.
+   */
+  cause?: Error;
+
+  constructor(message: string, { code, cause }: { code: string; cause?: Error }) {
     const prefix = '🔒 Clerk:';
     const regex = new RegExp(prefix.replace(' ', '\\s*'), 'i');
     const sanitized = message.replace(regex, '');
@@ -27,6 +32,7 @@ export class ClerkRuntimeError extends Error {
 
     Object.setPrototypeOf(this, ClerkRuntimeError.prototype);
 
+    this.cause = cause;
     this.code = code;
     this.message = _message;
     this.clerkRuntimeError = true;

packages/shared/src/loadClerkJsScript.ts

@@ -1,13 +1,15 @@
 import type { ClerkOptions, SDKMetadata, Without } from '@clerk/types';
 
-import { buildErrorThrower } from './error';
+import { buildErrorThrower, ClerkRuntimeError } from './error';
 import { createDevOrStagingUrlCache, parsePublishableKey } from './keys';
 import { loadScript } from './loadScript';
 import { isValidProxyUrl, proxyUrlToAbsoluteURL } from './proxy';
 import { addClerkPrefix } from './url';
 import { versionSelector } from './versionSelector';
 
-const FAILED_TO_LOAD_ERROR = 'Clerk: Failed to load Clerk';
+const ERROR_CODE = 'failed_to_load_clerk_js';
+const ERROR_CODE_TIMEOUT = 'failed_to_load_clerk_js_timeout';
+const FAILED_TO_LOAD_ERROR = 'Failed to load Clerk';
 
 const { isDevOrStagingUrl } = createDevOrStagingUrlCache();
 
@@ -96,7 +98,7 @@ function waitForClerkWithTimeout(timeoutMs: number): Promise<HTMLScriptElement |
       cleanup(timeoutId, pollInterval);
 
       if (!isClerkProperlyLoaded()) {
-        reject(new Error(FAILED_TO_LOAD_ERROR));
+        reject(new ClerkRuntimeError(FAILED_TO_LOAD_ERROR, { code: ERROR_CODE_TIMEOUT }));
       } else {
         resolve(null);
       }
@@ -162,8 +164,11 @@ const loadClerkJsScript = async (opts?: LoadClerkJsScriptOptions): Promise<HTMLS
     crossOrigin: 'anonymous',
     nonce: opts.nonce,
     beforeLoad: applyClerkJsScriptAttributes(opts),
-  }).catch(() => {
-    throw new Error(FAILED_TO_LOAD_ERROR);
+  }).catch(error => {
+    throw new ClerkRuntimeError(FAILED_TO_LOAD_ERROR + (error.message ? `, ${error.message}` : ''), {
+      code: ERROR_CODE,
+      cause: error,
+    });
   });
 
   return loadPromise;

packages/shared/src/loadScript.ts

@@ -21,7 +21,7 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
       }
 
       if (!document || !document.body) {
-        reject(NO_DOCUMENT_ERROR);
+        reject(new Error(NO_DOCUMENT_ERROR));
       }
 
       const script = document.createElement('script');
@@ -37,9 +37,9 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
         resolve(script);
       });
 
-      script.addEventListener('error', () => {
+      script.addEventListener('error', event => {
         script.remove();
-        reject();
+        reject(event.error ?? new Error(`failed to load script: ${src}`));
       });
 
       script.src = src;