clerk · jacekradko · Jan 9, 2026 · Jan 9, 2026 · Jan 9, 2026 · Jan 9, 2026
diff --git a/.changeset/light-eagles-stay.md b/.changeset/light-eagles-stay.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/integration/templates/custom-flows-react-vite/src/main.tsx b/integration/templates/custom-flows-react-vite/src/main.tsx
@@ -23,7 +23,7 @@ createRoot(document.getElementById('root')!).render(
         <ClerkProvider
           publishableKey={PUBLISHABLE_KEY}
           clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
-          clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL as string}
+          clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
           appearance={{
             options: {
               showOptionalFields: true,

diff --git a/integration/templates/expo-web/app/_layout.tsx b/integration/templates/expo-web/app/_layout.tsx
@@ -9,7 +9,7 @@ export default function RootLayout() {
       routerPush={(to: string) => router.push(to)}
       routerReplace={to => router.replace(to)}
       clerkJSUrl={process.env.EXPO_PUBLIC_CLERK_JS_URL}
-      clerkUiUrl={process.env.EXPO_PUBLIC_CLERK_UI_URL}
+      clerkUIUrl={process.env.EXPO_PUBLIC_CLERK_UI_URL}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/next-app-router/src/app/layout.tsx b/integration/templates/next-app-router/src/app/layout.tsx
@@ -12,6 +12,7 @@ export const metadata = {
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <ClerkProvider
+      prefetchUI={process.env.NEXT_PUBLIC_CLERK_PREFETCH_UI_DISABLED === 'true' ? false : undefined}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/react-cra/src/index.tsx b/integration/templates/react-cra/src/index.tsx
@@ -10,7 +10,7 @@ root.render(
     <ClerkProvider
       publishableKey={process.env.REACT_APP_CLERK_PUBLISHABLE_KEY as string}
       clerkJSUrl={process.env.REACT_APP_CLERK_JS as string}
-      clerkUiUrl={process.env.REACT_APP_CLERK_UI as string}
+      clerkUIUrl={process.env.REACT_APP_CLERK_UI as string}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/react-router-library/src/main.tsx b/integration/templates/react-router-library/src/main.tsx
@@ -15,7 +15,7 @@ createRoot(document.getElementById('root')!).render(
       <ClerkProvider
         publishableKey={PUBLISHABLE_KEY}
         clerkJSUrl={CLERK_JS_URL}
-        clerkUiUrl={CLERK_UI_URL}
+        clerkUIUrl={CLERK_UI_URL}
         appearance={{
           options: {
             showOptionalFields: true,

diff --git a/integration/templates/react-router-node/app/root.tsx b/integration/templates/react-router-node/app/root.tsx
@@ -33,7 +33,7 @@ export default function App({ loaderData }: Route.ComponentProps) {
     <ClerkProvider
       loaderData={loaderData}
       clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
-      clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL}
+      clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/react-vite/src/main.tsx b/integration/templates/react-vite/src/main.tsx
@@ -31,7 +31,7 @@ const Root = () => {
       // @ts-ignore
       publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY as string}
       clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
-      clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL as string}
+      clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
       routerPush={(to: string) => navigate(to)}
       routerReplace={(to: string) => navigate(to, { replace: true })}
       appearance={{

diff --git a/integration/templates/tanstack-react-start/src/routes/__root.tsx b/integration/templates/tanstack-react-start/src/routes/__root.tsx
@@ -29,7 +29,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
       <body>
         <ClerkProvider
           clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
-          clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL}
+          clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
           appearance={{
             options: {
               showOptionalFields: true,

diff --git a/integration/templates/vue-vite/src/main.ts b/integration/templates/vue-vite/src/main.ts
@@ -8,7 +8,7 @@ const app = createApp(App);
 app.use(clerkPlugin, {
   publishableKey: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY,
   clerkJSUrl: import.meta.env.VITE_CLERK_JS_URL,
-  clerkUiUrl: import.meta.env.VITE_CLERK_UI_URL,
+  clerkUIUrl: import.meta.env.VITE_CLERK_UI_URL,
   clerkJSVersion: import.meta.env.VITE_CLERK_JS_VERSION,
   appearance: {
     options: {

diff --git a/integration/tests/prefetch-ui.test.ts b/integration/tests/prefetch-ui.test.ts
@@ -0,0 +1,32 @@
+import { expect, test } from '@playwright/test';
+
+import type { Application } from '../models/application';
+import { appConfigs } from '../presets';
+
+test.describe('prefetchUI disabled @nextjs', () => {
+  test.describe.configure({ mode: 'serial' });
+  let app: Application;
+
+  test.beforeAll(async () => {
+    app = await appConfigs.next.appRouter.clone().commit();
+    await app.setup();
+    // Use withEmailCodes but disable the UI prefetching
+    const env = appConfigs.envs.withEmailCodes.clone().setEnvVariable('public', 'CLERK_PREFETCH_UI_DISABLED', 'true');
+    await app.withEnv(env);
+    await app.dev();
+  });
+
+  test.afterAll(async () => {
+    await app.teardown();
+  });
+
+  test('does not inject clerk-ui script when prefetchUI is disabled', async ({ page }) => {
+    await page.goto(app.serverUrl);
+
+    // Wait for clerk-js script to be present (ensures page has loaded)
+    await expect(page.locator('script[data-clerk-js-script]')).toBeAttached();
+
+    // clerk-ui script should NOT be present
+    await expect(page.locator('script[data-clerk-ui-script]')).not.toBeAttached();
+  });
+});
diff --git a/packages/astro/src/env.d.ts b/packages/astro/src/env.d.ts
@@ -4,9 +4,9 @@ interface InternalEnv {
   readonly PUBLIC_CLERK_FRONTEND_API?: string;
   readonly PUBLIC_CLERK_PUBLISHABLE_KEY?: string;
   readonly PUBLIC_CLERK_JS_URL?: string;
-  readonly PUBLIC_CLERK_UI_URL?: string;
-  readonly PUBLIC_CLERK_JS_VARIANT?: 'headless' | '';
   readonly PUBLIC_CLERK_JS_VERSION?: string;
+  readonly PUBLIC_CLERK_UI_URL?: string;
+  readonly PUBLIC_CLERK_PREFETCH_UI_DISABLED?: string;
   readonly CLERK_API_KEY?: string;
   readonly CLERK_API_URL?: string;
   readonly CLERK_API_VERSION?: string;

diff --git a/packages/astro/src/integration/create-integration.ts b/packages/astro/src/integration/create-integration.ts
@@ -20,9 +20,8 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
 
     // These are not provided when the "bundled" integration is used
     const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
-    const clerkUiUrl = (params as any)?.clerkUiUrl as string | undefined;
-    const clerkJSVariant = (params as any)?.clerkJSVariant as string | undefined;
     const clerkJSVersion = (params as any)?.clerkJSVersion as string | undefined;
+    const prefetchUI = (params as any)?.prefetchUI as boolean | undefined;
 
     return {
       name: '@clerk/astro/integration',
@@ -32,10 +31,6 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
             logger.error('Missing adapter, please update your Astro config to use one.');
           }
 
-          if (typeof clerkJSVariant !== 'undefined' && clerkJSVariant !== 'headless' && clerkJSVariant !== '') {
-            logger.error('Invalid value for clerkJSVariant. Acceptable values are `"headless"`, `""`, and `undefined`');
-          }
-
           const internalParams: ClerkOptions = {
             ...params,
             sdkMetadata: {
@@ -61,9 +56,8 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                 ...buildEnvVarFromOption(proxyUrl, 'PUBLIC_CLERK_PROXY_URL'),
                 ...buildEnvVarFromOption(domain, 'PUBLIC_CLERK_DOMAIN'),
                 ...buildEnvVarFromOption(clerkJSUrl, 'PUBLIC_CLERK_JS_URL'),
-                ...buildEnvVarFromOption(clerkUiUrl, 'PUBLIC_CLERK_UI_URL'),
-                ...buildEnvVarFromOption(clerkJSVariant, 'PUBLIC_CLERK_JS_VARIANT'),
                 ...buildEnvVarFromOption(clerkJSVersion, 'PUBLIC_CLERK_JS_VERSION'),
+                ...buildEnvVarFromOption(prefetchUI === false, 'PUBLIC_CLERK_PREFETCH_UI_DISABLED'),
               },
 
               ssr: {
@@ -170,14 +164,10 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_PROXY_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_DOMAIN: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_JS_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
-    PUBLIC_CLERK_UI_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
-    PUBLIC_CLERK_JS_VARIANT: envField.enum({
-      context: 'client',
-      access: 'public',
-      optional: true,
-      values: ['headless'],
-    }),
     PUBLIC_CLERK_JS_VERSION: envField.string({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_PREFETCH_UI_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_UI_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
+    PUBLIC_CLERK_UI_VERSION: envField.string({ context: 'client', access: 'public', optional: 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 }),
     CLERK_SECRET_KEY: envField.string({ context: 'server', access: 'secret' }),

diff --git a/packages/astro/src/internal/create-clerk-instance.ts b/packages/astro/src/internal/create-clerk-instance.ts
@@ -2,6 +2,7 @@ import {
   loadClerkJsScript,
   loadClerkUiScript,
   setClerkJsLoadingErrorPackageName,
+  shouldPrefetchClerkUi,
 } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkOptions } from '@clerk/shared/types';
 import type { ClerkUiConstructor } from '@clerk/shared/ui';
@@ -111,15 +112,20 @@ async function getClerkJsEntryChunk<TUi extends Ui = Ui>(options?: AstroClerkCre
 /**
  * Gets the ClerkUI constructor, either from options or by loading the script.
  * Returns early if window.__internal_ClerkUiCtor already exists.
+ * Returns undefined when prefetchUI={false} (no UI needed).
  */
 async function getClerkUiEntryChunk<TUi extends Ui = Ui>(
   options?: AstroClerkCreateInstanceParams<TUi>,
-): Promise<ClerkUiConstructor> {
+): Promise<ClerkUiConstructor | undefined> {
+  if (!shouldPrefetchClerkUi(options?.prefetchUI)) {
+    return undefined;
+  }
+
   if (options?.clerkUiCtor) {
     return options.clerkUiCtor;
   }
 
-  await loadClerkUiScript(options);
+  await loadClerkUiScript(options as any);
 
   if (!window.__internal_ClerkUiCtor) {
     throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');

diff --git a/packages/astro/src/internal/merge-env-vars-with-params.ts b/packages/astro/src/internal/merge-env-vars-with-params.ts
@@ -2,6 +2,26 @@ import { isTruthy } from '@clerk/shared/underscore';
 
 import type { AstroClerkIntegrationParams } from '../types';
 
+/**
+ * Merges `prefetchUI` param with env vars.
+ * - If param `prefetchUI` is explicitly `false`, return `false`
+ * - If env `PUBLIC_CLERK_PREFETCH_UI_DISABLED` is "true", return `false`
+ * - Otherwise return `undefined` (default behavior: prefetch UI)
+ */
+function mergePrefetchUIConfig(paramPrefetchUI: AstroClerkIntegrationParams['prefetchUI']): boolean | undefined {
+  // Explicit false from param takes precedence
+  if (paramPrefetchUI === false) {
+    return false;
+  }
+
+  // Check env var for disabled
+  if (import.meta.env.PUBLIC_CLERK_PREFETCH_UI_DISABLED === 'true') {
+    return false;
+  }
+
+  return undefined;
+}
+
 /**
  * @internal
  */
@@ -15,9 +35,9 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     publishableKey: paramPublishableKey,
     telemetry: paramTelemetry,
     clerkJSUrl: paramClerkJSUrl,
-    clerkUiUrl: paramClerkUiUrl,
-    clerkJSVariant: paramClerkJSVariant,
     clerkJSVersion: paramClerkJSVersion,
+    clerkUIUrl: paramClerkUiUrl,
+    prefetchUI: paramPrefetchUI,
     ...rest
   } = params || {};
 
@@ -28,10 +48,10 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     proxyUrl: paramProxy || import.meta.env.PUBLIC_CLERK_PROXY_URL,
     domain: paramDomain || import.meta.env.PUBLIC_CLERK_DOMAIN,
     publishableKey: paramPublishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
-    clerkUiUrl: paramClerkUiUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
     clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
-    clerkJSVariant: paramClerkJSVariant || import.meta.env.PUBLIC_CLERK_JS_VARIANT,
     clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,
+    clerkUIUrl: paramClerkUiUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
+    prefetchUI: mergePrefetchUIConfig(paramPrefetchUI),
     telemetry: paramTelemetry || {
       disabled: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DISABLED),
       debug: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DEBUG),

diff --git a/packages/astro/src/server/build-clerk-hotload-script.ts b/packages/astro/src/server/build-clerk-hotload-script.ts
@@ -1,46 +1,57 @@
-import { clerkJsScriptUrl, clerkUiScriptUrl } from '@clerk/shared/loadClerkJsScript';
+import { clerkJsScriptUrl, clerkUiScriptUrl, shouldPrefetchClerkUi } from '@clerk/shared/loadClerkJsScript';
 import type { APIContext } from 'astro';
 
 import { getSafeEnv } from './get-safe-env';
 
 function buildClerkHotloadScript(locals: APIContext['locals']) {
+  const env = getSafeEnv(locals);
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  const publishableKey = getSafeEnv(locals).pk!;
+  const publishableKey = env.pk!;
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  const proxyUrl = getSafeEnv(locals).proxyUrl!;
+  const proxyUrl = env.proxyUrl!;
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  const domain = getSafeEnv(locals).domain!;
+  const domain = env.domain!;
+
   const clerkJsScriptSrc = clerkJsScriptUrl({
-    clerkJSUrl: getSafeEnv(locals).clerkJsUrl,
-    clerkJSVariant: getSafeEnv(locals).clerkJsVariant,
-    clerkJSVersion: getSafeEnv(locals).clerkJsVersion,
-    domain,
-    proxyUrl,
-    publishableKey,
-  });
-  const clerkUiScriptSrc = clerkUiScriptUrl({
-    clerkUiUrl: getSafeEnv(locals).clerkUiUrl,
+    clerkJSUrl: env.clerkJsUrl,
+    clerkJSVersion: env.clerkJsVersion,
     domain,
     proxyUrl,
     publishableKey,
   });
-  return `
+
+  const clerkJsScript = `
   <script src="${clerkJsScriptSrc}"
   data-clerk-js-script
   async
   crossOrigin='anonymous'
   ${publishableKey ? `data-clerk-publishable-key="${publishableKey}"` : ``}
   ${proxyUrl ? `data-clerk-proxy-url="${proxyUrl}"` : ``}
   ${domain ? `data-clerk-domain="${domain}"` : ``}
-  ></script>
+  ></script>`;
+
+  if (!shouldPrefetchClerkUi(env.prefetchUI)) {
+    return clerkJsScript + '\n';
+  }
+
+  const clerkUiScriptSrc = clerkUiScriptUrl({
+    clerkUIUrl: env.clerkUIUrl,
+    domain,
+    proxyUrl,
+    publishableKey,
+  });
+
+  const clerkUiScript = `
   <script src="${clerkUiScriptSrc}"
   data-clerk-ui-script
   async
   crossOrigin='anonymous'
   ${publishableKey ? `data-clerk-publishable-key="${publishableKey}"` : ``}
   ${proxyUrl ? `data-clerk-proxy-url="${proxyUrl}"` : ``}
   ${domain ? `data-clerk-domain="${domain}"` : ``}
-  ></script>\n`;
+  ></script>`;
+
+  return clerkJsScript + clerkUiScript + '\n';
 }
 
 export { buildClerkHotloadScript };
diff --git a/packages/astro/src/server/get-safe-env.ts b/packages/astro/src/server/get-safe-env.ts
@@ -21,6 +21,8 @@ function getContextEnvVar(envVarName: keyof InternalEnv, contextOrLocals: Contex
  * @internal
  */
 function getSafeEnv(context: ContextOrLocals) {
+  const prefetchUIDisabled = getContextEnvVar('PUBLIC_CLERK_PREFETCH_UI_DISABLED', context) === 'true';
+
   return {
     domain: getContextEnvVar('PUBLIC_CLERK_DOMAIN', context),
     isSatellite: getContextEnvVar('PUBLIC_CLERK_IS_SATELLITE', context) === 'true',
@@ -31,9 +33,9 @@ function getSafeEnv(context: ContextOrLocals) {
     signInUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_IN_URL', context),
     signUpUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_UP_URL', context),
     clerkJsUrl: getContextEnvVar('PUBLIC_CLERK_JS_URL', context),
-    clerkUiUrl: getContextEnvVar('PUBLIC_CLERK_UI_URL', context),
-    clerkJsVariant: getContextEnvVar('PUBLIC_CLERK_JS_VARIANT', context) as 'headless' | '' | undefined,
     clerkJsVersion: getContextEnvVar('PUBLIC_CLERK_JS_VERSION', context),
+    clerkUIUrl: getContextEnvVar('PUBLIC_CLERK_UI_URL', context),
+    prefetchUI: prefetchUIDisabled ? false : undefined,
     apiVersion: getContextEnvVar('CLERK_API_VERSION', context),
     apiUrl: getContextEnvVar('CLERK_API_URL', context),
     telemetryDisabled: isTruthy(getContextEnvVar('PUBLIC_CLERK_TELEMETRY_DISABLED', context)),

diff --git a/packages/astro/src/types.ts b/packages/astro/src/types.ts
@@ -30,12 +30,17 @@ type AstroClerkIntegrationParams<TUi extends Ui = Ui> = Without<
   MultiDomainAndOrProxyPrimitives & {
     appearance?: Appearance<TUi>;
     clerkJSUrl?: string;
-    clerkJSVariant?: 'headless' | '';
     clerkJSVersion?: string;
     /**
      * The URL that `@clerk/ui` should be hot-loaded from.
      */
-    clerkUiUrl?: string;
+    clerkUIUrl?: string;
+    /**
+     * Controls prefetching of the `@clerk/ui` script.
+     * - `false` - Skip prefetching the UI (for custom UIs using Control Components)
+     * - `undefined` (default) - Prefetch UI normally
+     */
+    prefetchUI?: boolean;
   };
 
 type AstroClerkCreateInstanceParams<TUi extends Ui = Ui> = AstroClerkIntegrationParams<TUi> & {

diff --git a/packages/chrome-extension/src/internal/clerk.ts b/packages/chrome-extension/src/internal/clerk.ts
@@ -35,12 +35,6 @@ export function createClerkClient({
   storageCache = BrowserStorageCache,
   syncHost,
 }: CreateClerkClientOptions) {
-  if (scope === SCOPE.BACKGROUND) {
-    // TODO @nikos
-    // @ts-expect-error will be replaced by clerk ui
-    Clerk.mountComponentRenderer = undefined;
-  }
-
   // Don't cache background scripts as it can result in out-of-sync client information.
   if (clerk && scope !== SCOPE.BACKGROUND) {
     return clerk;

diff --git a/packages/chrome-extension/src/internal/utils/request-handler.ts b/packages/chrome-extension/src/internal/utils/request-handler.ts
@@ -7,7 +7,7 @@ type Handler = Parameters<Clerk['__internal_onBeforeRequest']>[0];
 type Req = Parameters<Handler>[0];
 
 /** Append the JWT to the FAPI request */
-export function requestHandler(jwtHandler: JWTHandler, { isProd }: { isProd: boolean }) {
+export function requestHandler(jwtHandler: JWTHandler, { isProd }: { isProd: boolean }): Handler {
   const handler: Handler = async requestInit => {
     requestInit.credentials = 'omit';
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		---
		---
Comment on lines +1 to +2 Copy link Contributor coderabbitai bot Jan 21, 2026 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. ⚠️ Potential issue \| 🟠 Major Empty changeset file - missing package entries and description. This changeset is empty but the PR introduces breaking changes (removal of `clerkJSVariant`, `@clerk/clerk-js/headless` import path, new `ui` prop). The changeset should document affected packages and their semver bumps. 🤖 Prompt for AI Agents In @.changeset/light-eagles-stay.md around lines 1 - 2, The changeset is empty and must document the breaking changes introduced: explicitly list affected package names and semver bumps (use major bumps for breaking changes), describe the removals of clerkJSVariant and the old import path `@clerk/clerk-js/headless`, and note the new ui prop and its migration steps; update the changeset body to include a short summary, per-package entries (e.g., package-name: major), and a brief migration note explaining how to replace/remove clerkJSVariant, how to update import paths to the new entrypoints, and how to adopt the new ui prop so consumers can upgrade safely.