feat(shared): make clerkJSUrl, clerkJSVersion, clerkUIUrl internal

.changeset/internal-clerk-js-ui-props.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': minor
+'@clerk/nextjs': minor
+'@clerk/astro': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+'@clerk/express': minor
+'@clerk/nuxt': minor
+---
+
+Remove `clerkJSUrl`, `clerkJSVersion`, `clerkUIUrl`, and `clerkUIVersion` props and replace with `__internal_clerkJSUrl`, `__internal_clerkJSVersion`, `__internal_clerkUIUrl`, and `__internal_clerkUIVersion` internal-only options. Use `@clerk/upgrade` to migrate.

.changeset/remove-clerk-ui-version.md

@@ -0,0 +1,11 @@
+---
+'@clerk/shared': minor
+'@clerk/nextjs': minor
+'@clerk/astro': minor
+'@clerk/react-router': minor
+'@clerk/tanstack-react-start': minor
+'@clerk/express': minor
+'@clerk/nuxt': minor
+---
+
+Remove `clerkUIVersion` and `clerkJSVersion` props across all SDKs. Use `@clerk/upgrade` to migrate to the new `__internal_` prefixed props if needed.

integration/templates/custom-flows-react-vite/src/main.tsx

@@ -14,8 +14,8 @@ createRoot(document.getElementById('root')!).render(
     <div className='bg-muted flex min-h-svh flex-col items-center justify-center gap-6 p-6 md:p-10'>
       <div className='flex w-full max-w-sm flex-col gap-6'>
         <ClerkProvider
-          clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
-          clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
+          __internal_clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
+          __internal_clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
           appearance={{
             options: {
               showOptionalFields: true,

integration/templates/expo-web/app/_layout.tsx

@@ -8,8 +8,8 @@ export default function RootLayout() {
     <ClerkProvider
       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}
+      __internal_clerkJSUrl={process.env.EXPO_PUBLIC_CLERK_JS_URL}
+      __internal_clerkUIUrl={process.env.EXPO_PUBLIC_CLERK_UI_URL}
       appearance={{
         options: {
           showOptionalFields: true,

integration/templates/react-cra/src/index.tsx

@@ -9,8 +9,8 @@ root.render(
   <React.StrictMode>
     <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}
+      __internal_clerkJSUrl={process.env.REACT_APP_CLERK_JS as string}
+      __internal_clerkUIUrl={process.env.REACT_APP_CLERK_UI as string}
       appearance={{
         options: {
           showOptionalFields: true,

integration/templates/react-router-library/src/main.tsx

@@ -14,8 +14,8 @@ createRoot(document.getElementById('root')!).render(
     <BrowserRouter>
       <ClerkProvider
         publishableKey={PUBLISHABLE_KEY}
-        clerkJSUrl={CLERK_JS_URL}
-        clerkUIUrl={CLERK_UI_URL}
+        __internal_clerkJSUrl={CLERK_JS_URL}
+        __internal_clerkUIUrl={CLERK_UI_URL}
         appearance={{
           options: {
             showOptionalFields: true,

integration/templates/react-router-node/app/root.tsx

@@ -32,8 +32,8 @@ export default function App({ loaderData }: Route.ComponentProps) {
   return (
     <ClerkProvider
       loaderData={loaderData}
-      clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
-      clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
+      __internal_clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
+      __internal_clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
       appearance={{
         options: {
           showOptionalFields: true,

integration/templates/react-vite/src/main.tsx

@@ -29,8 +29,8 @@ const Root = () => {
   const navigate = useNavigate();
   return (
     <ClerkProvider
-      clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
-      clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
+      __internal_clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
+      __internal_clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
       routerPush={(to: string) => navigate(to)}
       routerReplace={(to: string) => navigate(to, { replace: true })}
       appearance={{

integration/templates/tanstack-react-start/src/routes/__root.tsx

@@ -28,8 +28,8 @@ function RootDocument({ children }: { children: React.ReactNode }) {
       </head>
       <body>
         <ClerkProvider
-          clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
-          clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
+          __internal_clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
+          __internal_clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
           appearance={{
             options: {
               showOptionalFields: true,

integration/templates/vue-vite/src/main.ts

@@ -7,9 +7,9 @@ import router from './router';
 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,
-  clerkJSVersion: import.meta.env.VITE_CLERK_JS_VERSION,
+  __internal_clerkJSUrl: import.meta.env.VITE_CLERK_JS_URL,
+  __internal_clerkUIUrl: import.meta.env.VITE_CLERK_UI_URL,
+  __internal_clerkJSVersion: import.meta.env.VITE_CLERK_JS_VERSION,
   appearance: {
     options: {
       showOptionalFields: true,

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

@@ -20,9 +20,9 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
     const { proxyUrl, isSatellite, domain, signInUrl, signUpUrl, enableEnvSchema = true } = params || {};
 
     // These are not provided when the "bundled" integration is used
-    const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
-    const clerkJSVersion = (params as any)?.clerkJSVersion as string | undefined;
-    const clerkUIVersion = (params as any)?.clerkUIVersion as string | undefined;
+    const clerkJSUrl = (params as any)?.__internal_clerkJSUrl as string | undefined;
+    const clerkJSVersion = (params as any)?.__internal_clerkJSVersion as string | undefined;
+    const clerkUIVersion = (params as any)?.__internal_clerkUIVersion as string | undefined;
     const prefetchUI = (params as any)?.prefetchUI as boolean | undefined;
     const hasUI = !!(params as any)?.ui;
 

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

@@ -42,7 +42,7 @@ describe('getClerkUIEntryChunk', () => {
     (window as any).Clerk = undefined;
   });
 
-  it('preserves clerkUIUrl from options', async () => {
+  it('preserves __internal_clerkUIUrl from options', async () => {
     mockLoadClerkUIScript.mockImplementation(async () => {
       (window as any).__internal_ClerkUICtor = mockClerkUICtor;
       return null;
@@ -59,18 +59,18 @@ describe('getClerkUIEntryChunk', () => {
     // Dynamically import to get fresh module with mocks
     const { createClerkInstance } = await import('../create-clerk-instance');
 
-    // Call createClerkInstance with clerkUIUrl
+    // Call createClerkInstance with __internal_clerkUIUrl
     await createClerkInstance({
       publishableKey: 'pk_test_xxx',
-      clerkUIUrl: 'https://custom.selfhosted.example.com/ui.js',
+      __internal_clerkUIUrl: 'https://custom.selfhosted.example.com/ui.js',
     });
 
     expect(mockLoadClerkUIScript).toHaveBeenCalled();
     const loadClerkUIScriptCall = mockLoadClerkUIScript.mock.calls[0]?.[0] as Record<string, unknown>;
-    expect(loadClerkUIScriptCall?.clerkUIUrl).toBe('https://custom.selfhosted.example.com/ui.js');
+    expect(loadClerkUIScriptCall?.__internal_clerkUIUrl).toBe('https://custom.selfhosted.example.com/ui.js');
   });
 
-  it('does not set clerkUIUrl when not provided', async () => {
+  it('does not set __internal_clerkUIUrl when not provided', async () => {
     mockLoadClerkUIScript.mockImplementation(async () => {
       (window as any).__internal_ClerkUICtor = mockClerkUICtor;
       return null;
@@ -92,6 +92,6 @@ describe('getClerkUIEntryChunk', () => {
 
     expect(mockLoadClerkUIScript).toHaveBeenCalled();
     const loadClerkUIScriptCall = mockLoadClerkUIScript.mock.calls[0]?.[0] as Record<string, unknown>;
-    expect(loadClerkUIScriptCall?.clerkUIUrl).toBeUndefined();
+    expect(loadClerkUIScriptCall?.__internal_clerkUIUrl).toBeUndefined();
   });
 });

packages/astro/src/internal/merge-env-vars-with-params.ts

@@ -1,3 +1,4 @@
+import type { InternalClerkScriptProps } from '@clerk/shared/types';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import type { AstroClerkIntegrationParams, InternalRuntimeOptions } from '../types';
@@ -25,7 +26,7 @@ function mergePrefetchUIConfig(paramPrefetchUI: AstroClerkIntegrationParams['pre
 /**
  * @internal
  */
-const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & InternalRuntimeOptions) => {
+const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & InternalRuntimeOptions & InternalClerkScriptProps) => {
   const {
     signInUrl: paramSignIn,
     signUpUrl: paramSignUp,
@@ -34,10 +35,10 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & InternalR
     domain: paramDomain,
     publishableKey: paramPublishableKey,
     telemetry: paramTelemetry,
-    clerkJSUrl: paramClerkJSUrl,
-    clerkJSVersion: paramClerkJSVersion,
-    clerkUIUrl: paramClerkUIUrl,
-    clerkUIVersion: paramClerkUIVersion,
+    __internal_clerkJSUrl: paramClerkJSUrl,
+    __internal_clerkJSVersion: paramClerkJSVersion,
+    __internal_clerkUIUrl: paramClerkUIUrl,
+    __internal_clerkUIVersion: paramClerkUIVersion,
     prefetchUI: paramPrefetchUI,
     ...rest
   } = params || {};
@@ -53,10 +54,10 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & InternalR
     // In keyless mode, use server-injected publishableKey from params
     publishableKey:
       paramPublishableKey || internalOptions?.publishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
-    clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
-    clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,
-    clerkUIUrl: paramClerkUIUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
-    clerkUIVersion: paramClerkUIVersion || import.meta.env.PUBLIC_CLERK_UI_VERSION,
+    __internal_clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
+    __internal_clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,
+    __internal_clerkUIUrl: paramClerkUIUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
+    __internal_clerkUIVersion: paramClerkUIVersion || import.meta.env.PUBLIC_CLERK_UI_VERSION,
     prefetchUI: mergePrefetchUIConfig(paramPrefetchUI),
     telemetry: paramTelemetry || {
       disabled: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DISABLED),

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

@@ -13,8 +13,8 @@ function buildClerkHotloadScript(locals: APIContext['locals']) {
   const domain = env.domain!;
 
   const clerkJsScriptSrc = clerkJSScriptUrl({
-    clerkJSUrl: env.clerkJsUrl,
-    clerkJSVersion: env.clerkJsVersion,
+    __internal_clerkJSUrl: env.clerkJsUrl,
+    __internal_clerkJSVersion: env.clerkJsVersion,
     domain,
     proxyUrl,
     publishableKey,
@@ -35,8 +35,8 @@ function buildClerkHotloadScript(locals: APIContext['locals']) {
   }
 
   const clerkUIScriptSrc = clerkUIScriptUrl({
-    clerkUIUrl: env.clerkUIUrl,
-    clerkUIVersion: env.clerkUIVersion,
+    __internal_clerkUIUrl: env.clerkUIUrl,
+    __internal_clerkUIVersion: env.clerkUIVersion,
     domain,
     proxyUrl,
     publishableKey,

packages/astro/src/types.ts

@@ -2,6 +2,7 @@ import type {
   Clerk,
   ClerkOptions,
   ClientResource,
+  InternalClerkScriptProps,
   MultiDomainAndOrProxyPrimitives,
   ProtectParams,
   ShowProps,
@@ -29,16 +30,6 @@ type AstroClerkIntegrationParams<TUi extends Ui = Ui> = Without<
 > &
   MultiDomainAndOrProxyPrimitives & {
     appearance?: Appearance<TUi>;
-    clerkJSUrl?: string;
-    clerkJSVersion?: string;
-    /**
-     * The URL that `@clerk/ui` should be hot-loaded from.
-     */
-    clerkUIUrl?: string;
-    /**
-     * The npm version for `@clerk/ui`.
-     */
-    clerkUIVersion?: string;
     /**
      * Controls prefetching of the `@clerk/ui` script.
      * - `false` - Skip prefetching the UI (for custom UIs using Control Components)
@@ -47,9 +38,10 @@ type AstroClerkIntegrationParams<TUi extends Ui = Ui> = Without<
     prefetchUI?: boolean;
   };
 
-type AstroClerkCreateInstanceParams<TUi extends Ui = Ui> = AstroClerkIntegrationParams<TUi> & {
-  publishableKey: string;
-};
+type AstroClerkCreateInstanceParams<TUi extends Ui = Ui> = AstroClerkIntegrationParams<TUi> &
+  InternalClerkScriptProps & {
+    publishableKey: string;
+  };
 
 /**
  * @internal

packages/chrome-extension/src/react/ClerkProvider.tsx

@@ -1,6 +1,6 @@
 import type { Clerk } from '@clerk/clerk-js/no-rhc';
 import type { ClerkProviderProps as ClerkReactProviderProps } from '@clerk/react';
-import { ClerkProvider as ClerkReactProvider } from '@clerk/react';
+import { InternalClerkProvider as ClerkReactProvider } from '@clerk/react/internal';
 import { ui } from '@clerk/ui';
 import React from 'react';
 

packages/expo/src/provider/ClerkProvider.tsx

@@ -1,18 +1,15 @@
 import '../polyfills';
 
-import { ClerkProvider as ClerkReactProvider } from '@clerk/react';
-import type { Ui } from '@clerk/react/internal';
+import type { ClerkProviderProps as ReactClerkProviderProps } from '@clerk/react';
+import { InternalClerkProvider as ClerkReactProvider, type Ui } from '@clerk/react/internal';
 import * as WebBrowser from 'expo-web-browser';
 
 import type { TokenCache } from '../cache/types';
 import { isNative, isWeb } from '../utils/runtime';
 import { getClerkInstance } from './singleton';
 import type { BuildClerkOptions } from './singleton/types';
 
-export type ClerkProviderProps<TUi extends Ui = Ui> = Omit<
-  React.ComponentProps<typeof ClerkReactProvider<TUi>>,
-  'publishableKey'
-> & {
+export type ClerkProviderProps<TUi extends Ui = Ui> = Omit<ReactClerkProviderProps<TUi>, 'publishableKey'> & {
   /**
    * Your Clerk publishable key, available in the Clerk Dashboard.
    * This is required for React Native / Expo apps. Environment variables inside node_modules

packages/express/src/utils.ts

@@ -11,10 +11,10 @@ export const requestHasAuthObject = (req: ExpressRequest): req is ExpressRequest
 export const loadClientEnv = () => {
   return {
     publishableKey: process.env.CLERK_PUBLISHABLE_KEY || '',
-    clerkJSUrl: process.env.CLERK_JS || process.env.CLERK_JS_URL || '',
-    clerkJSVersion: process.env.CLERK_JS_VERSION || '',
-    clerkUIUrl: process.env.CLERK_UI_URL || '',
-    clerkUIVersion: process.env.CLERK_UI_VERSION || '',
+    __internal_clerkJSUrl: process.env.CLERK_JS || process.env.CLERK_JS_URL || '',
+    __internal_clerkJSVersion: process.env.CLERK_JS_VERSION || '',
+    __internal_clerkUIUrl: process.env.CLERK_UI_URL || '',
+    __internal_clerkUIVersion: process.env.CLERK_UI_VERSION || '',
     prefetchUI: process.env.CLERK_PREFETCH_UI === 'false' ? false : undefined,
   };
 };

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,5 @@
 'use client';
-import { ClerkProvider as ReactClerkProvider } from '@clerk/react';
-import type { Ui } from '@clerk/react/internal';
+import { InternalClerkProvider as ReactClerkProvider, type Ui } from '@clerk/react/internal';
 import { InitialStateProvider } from '@clerk/shared/react';
 import dynamic from 'next/dynamic';
 import { useRouter } from 'next/navigation';

packages/nextjs/src/app-router/client/ClerkScripts.tsx

@@ -5,7 +5,8 @@ import { useClerkNextOptions } from '../../client-boundary/NextOptionsContext';
 import { ClerkScriptTags } from '../../utils/clerk-script-tags';
 
 export function ClerkScripts() {
-  const { publishableKey, clerkJSUrl, clerkJSVersion, clerkUIUrl, nonce, prefetchUI } = useClerkNextOptions();
+  const { publishableKey, __internal_clerkJSUrl, __internal_clerkJSVersion, __internal_clerkUIUrl, nonce, prefetchUI } =
+    useClerkNextOptions();
   const { domain, proxyUrl } = useClerk();
 
   if (!publishableKey) {
@@ -15,9 +16,9 @@ export function ClerkScripts() {
   return (
     <ClerkScriptTags
       publishableKey={publishableKey}
-      clerkJSUrl={clerkJSUrl}
-      clerkJSVersion={clerkJSVersion}
-      clerkUIUrl={clerkUIUrl}
+      __internal_clerkJSUrl={__internal_clerkJSUrl}
+      __internal_clerkJSVersion={__internal_clerkJSVersion}
+      __internal_clerkUIUrl={__internal_clerkUIUrl}
       nonce={nonce}
       domain={domain}
       proxyUrl={proxyUrl}

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -40,9 +40,10 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
     <Suspense>
       <DynamicClerkScripts
         publishableKey={propsWithEnvs.publishableKey}
-        clerkJSUrl={propsWithEnvs.clerkJSUrl}
-        clerkJSVersion={propsWithEnvs.clerkJSVersion}
-        clerkUIUrl={propsWithEnvs.clerkUIUrl}
+        __internal_clerkJSUrl={propsWithEnvs.__internal_clerkJSUrl}
+        __internal_clerkJSVersion={propsWithEnvs.__internal_clerkJSVersion}
+        __internal_clerkUIUrl={propsWithEnvs.__internal_clerkUIUrl}
+        __internal_clerkUIVersion={propsWithEnvs.__internal_clerkUIVersion}
         domain={propsWithEnvs.domain}
         proxyUrl={propsWithEnvs.proxyUrl}
         prefetchUI={propsWithEnvs.prefetchUI}