feat(clerk-js): Add js prop for bundling clerk-js with applications

Add a `js` prop to ClerkProvider (React, Next.js, Vue, Astro) that allows
bundling @clerk/clerk-js with the application instead of loading from CDN,
mirroring the established `ui` prop pattern from @clerk/ui.

- Add branded Js type and bundled/server/entry exports to @clerk/clerk-js
- Add js prop to ClerkOptions in @clerk/shared
- Support bundled js.ClerkJS in isomorphicClerk with CDN skip
- Add Next.js RSC resolution with cached promise pattern
- Add Vue plugin support for bundled ClerkJS constructor
- Add Astro integration support with PUBLIC_CLERK_SKIP_JS_CDN env var
- Add export snapshot tests for @clerk/clerk-js

Author: jacekradko

.changeset/shiny-owls-dance.md

@@ -1,4 +1,5 @@
 ---
+'@clerk/clerk-js': minor
 '@clerk/ui': minor
 '@clerk/react': minor
 '@clerk/nextjs': minor
@@ -8,4 +9,4 @@
 '@clerk/shared': minor
 ---
 
-Add `ui` prop to `ClerkProvider` for passing `@clerk/ui`
+Add `ui` and `js` props to `ClerkProvider` for passing `@clerk/ui` and `@clerk/clerk-js`

packages/astro/src/env.d.ts

@@ -8,6 +8,7 @@ interface InternalEnv {
   readonly PUBLIC_CLERK_UI_URL?: string;
   readonly PUBLIC_CLERK_UI_VERSION?: string;
   readonly PUBLIC_CLERK_PREFETCH_UI?: string;
+  readonly PUBLIC_CLERK_SKIP_JS_CDN?: string;
   readonly CLERK_API_KEY?: string;
   readonly CLERK_API_URL?: string;
   readonly CLERK_API_VERSION?: string;

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

@@ -24,6 +24,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
     const clerkUIVersion = (params as any)?.clerkUIVersion as string | undefined;
     const prefetchUI = (params as any)?.prefetchUI as boolean | undefined;
     const hasUI = !!(params as any)?.ui;
+    const hasJS = !!(params as any)?.js;
 
     return {
       name: '@clerk/astro/integration',
@@ -64,6 +65,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                   prefetchUI === false || hasUI ? 'false' : undefined,
                   'PUBLIC_CLERK_PREFETCH_UI',
                 ),
+                ...buildEnvVarFromOption(hasJS ? 'true' : undefined, 'PUBLIC_CLERK_SKIP_JS_CDN'),
               },
 
               ssr: {
@@ -173,6 +175,7 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_JS_VERSION: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_UI_VERSION: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_PREFETCH_UI: envField.string({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_SKIP_JS_CDN: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_UI_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_TELEMETRY_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_TELEMETRY_DEBUG: envField.boolean({ context: 'client', access: 'public', optional: true }),

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

@@ -3,7 +3,7 @@ import {
   loadClerkUIScript,
   setClerkJSLoadingErrorPackageName,
 } from '@clerk/shared/loadClerkJsScript';
-import type { ClerkOptions } from '@clerk/shared/types';
+import type { BrowserClerkConstructor, ClerkOptions } from '@clerk/shared/types';
 import type { ClerkUIConstructor } from '@clerk/shared/ui';
 import type { Ui } from '@clerk/ui/internal';
 
@@ -102,9 +102,18 @@ function updateClerkOptions<TUi extends Ui = Ui>(options: AstroClerkUpdateOption
 
 /**
  * Loads clerk-js script if not already loaded.
+ * Uses bundled ClerkJS constructor when js.ClerkJS is present.
  * Returns early if window.Clerk already exists.
  */
 async function getClerkJsEntryChunk<TUi extends Ui = Ui>(options?: AstroClerkCreateInstanceParams<TUi>): Promise<void> {
+  const jsProp = options as { js?: { ClerkJS?: BrowserClerkConstructor } } | undefined;
+  if (jsProp?.js?.ClerkJS) {
+    window.Clerk = new jsProp.js.ClerkJS(options!.publishableKey, {
+      proxyUrl: options?.proxyUrl as string,
+      domain: options?.domain as string,
+    }) as any;
+    return;
+  }
   await loadClerkJSScript(options);
 }
 

packages/astro/src/server/build-clerk-hotload-script.ts

@@ -12,6 +12,30 @@ function buildClerkHotloadScript(locals: APIContext['locals']) {
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
   const domain = env.domain!;
 
+  // Skip ClerkJS CDN script when js prop is bundled
+  if (env.skipJsCdn) {
+    if (env.prefetchUI === false) {
+      return '\n';
+    }
+
+    const clerkUIScriptSrc = clerkUIScriptUrl({
+      clerkUIUrl: env.clerkUIUrl,
+      clerkUIVersion: env.clerkUIVersion,
+      domain,
+      proxyUrl,
+      publishableKey,
+    });
+
+    const clerkUIPreload = `
+  <link rel="preload"
+  href="${clerkUIScriptSrc}"
+  as="script"
+  crossOrigin="anonymous"
+  />`;
+
+    return clerkUIPreload + '\n';
+  }
+
   const clerkJsScriptSrc = clerkJSScriptUrl({
     clerkJSUrl: env.clerkJsUrl,
     clerkJSVersion: env.clerkJsVersion,

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

@@ -35,6 +35,7 @@ function getSafeEnv(context: ContextOrLocals) {
     clerkUIUrl: getContextEnvVar('PUBLIC_CLERK_UI_URL', context),
     clerkUIVersion: getContextEnvVar('PUBLIC_CLERK_UI_VERSION', context),
     prefetchUI: getContextEnvVar('PUBLIC_CLERK_PREFETCH_UI', context) === 'false' ? false : undefined,
+    skipJsCdn: getContextEnvVar('PUBLIC_CLERK_SKIP_JS_CDN', context) === 'true',
     apiVersion: getContextEnvVar('CLERK_API_VERSION', context),
     apiUrl: getContextEnvVar('CLERK_API_URL', context),
     telemetryDisabled: isTruthy(getContextEnvVar('PUBLIC_CLERK_TELEMETRY_DISABLED', context)),

packages/clerk-js/package.json

@@ -62,7 +62,7 @@
       "default": "./dist/esm/entry.mjs"
     },
     "./internal": {
-      "types": "./dist/esm/internal/index.d.mts",
+      "types": "./dist/types/internal/index.d.ts",
       "import": "./dist/esm/internal/index.mjs",
       "default": "./dist/esm/internal/index.mjs"
     }

packages/clerk-js/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -0,0 +1,16 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`module exports > bundled export (bundled.ts) > should have the expected shape 1`] = `
+[
+  "ClerkJS",
+  "__brand",
+  "version",
+]
+`;
+
+exports[`module exports > server export (server.ts) > should have the expected shape 1`] = `
+[
+  "__brand",
+  "version",
+]
+`;

packages/clerk-js/src/__tests__/exports.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import { js } from '../bundled';
+import { js as serverJs } from '../server';
+
+describe('module exports', () => {
+  describe('bundled export (bundled.ts)', () => {
+    it('should have the expected shape', () => {
+      expect(Object.keys(js).sort()).toMatchSnapshot();
+    });
+
+    it('should include __brand marker', () => {
+      expect((js as any).__brand).toBe('__clerkJS');
+    });
+
+    it('should include ClerkJS constructor', () => {
+      expect((js as any).ClerkJS).toBeDefined();
+      expect(typeof (js as any).ClerkJS).toBe('function');
+    });
+
+    it('should include version', () => {
+      expect((js as any).version).toBeDefined();
+      expect(typeof (js as any).version).toBe('string');
+    });
+  });
+
+  describe('server export (server.ts)', () => {
+    it('should have the expected shape', () => {
+      expect(Object.keys(serverJs).sort()).toMatchSnapshot();
+    });
+
+    it('should include __brand marker', () => {
+      expect((serverJs as any).__brand).toBe('__clerkJS');
+    });
+
+    it('should NOT include ClerkJS constructor', () => {
+      expect((serverJs as any).ClerkJS).toBeUndefined();
+    });
+
+    it('should include version', () => {
+      expect((serverJs as any).version).toBeDefined();
+      expect(typeof (serverJs as any).version).toBe('string');
+    });
+  });
+});

packages/clerk-js/src/entry.ts

@@ -2,4 +2,4 @@
  * Entry point for dynamic import of ClerkJS constructor.
  * Used by the SDK when the js prop is a server-safe marker (without ClerkJS constructor).
  */
-export { Clerk as ClerkJs } from './core/clerk';
+export { Clerk as ClerkJS } from './core/clerk';