feat: promote OAuthConsent to public API across all SDKs

wobsoriano · wobsoriano · commit 2c3368465312 · 2026-04-22T11:05:09.000-07:00
- Rename __internal_OAuthConsentProps to OAuthConsentProps in @clerk/shared - Rename __internal_mountOAuthConsent / __internal_unmountOAuthConsent to mountOAuthConsent / unmountOAuthConsent on the Clerk interface and clerk-js - Add OAuthConsent and useOAuthConsent to the public exports of @clerk/react, @clerk/nextjs, @clerk/vue, @clerk/nuxt, and @clerk/astro - Add @deprecated JSDoc to the existing /internal re-exports in @clerk/react and @clerk/nextjs pointing consumers to the public paths - Update @clerk/ui type references to the renamed public types
diff --git a/docs/superpowers/specs/2026-04-14-accounts-oauth-consent-refactor-design.md b/docs/superpowers/specs/2026-04-14-accounts-oauth-consent-refactor-design.md
diff --git a/packages/astro/src/astro-components/index.ts b/packages/astro/src/astro-components/index.ts
@@ -28,5 +28,6 @@ export { default as OrganizationList } from './interactive/OrganizationList.astr
 export { default as CreateOrganization } from './interactive/CreateOrganization.astro';
 export { default as GoogleOneTap } from './interactive/GoogleOneTap.astro';
 export { default as Waitlist } from './interactive/Waitlist.astro';
+export { default as OAuthConsent } from './interactive/OAuthConsent.astro';
 export { default as PricingTable } from './interactive/PricingTable.astro';
 export { default as APIKeys } from './interactive/APIKeys.astro';
diff --git a/packages/astro/src/astro-components/interactive/OAuthConsent.astro b/packages/astro/src/astro-components/interactive/OAuthConsent.astro
@@ -0,0 +1,11 @@
+---
+import type { OAuthConsentProps } from '@clerk/shared/types';
+type Props = OAuthConsentProps;
+
+import InternalUIComponentRenderer from './InternalUIComponentRenderer.astro';
+---
+
+<InternalUIComponentRenderer
+  {...Astro.props}
+  component='oauth-consent'
+/>
diff --git a/packages/astro/src/internal/mount-clerk-astro-js-components.ts b/packages/astro/src/internal/mount-clerk-astro-js-components.ts
@@ -21,6 +21,7 @@ const mountAllClerkAstroJSComponents = () => {
     waitlist: 'mountWaitlist',
     'pricing-table': 'mountPricingTable',
     'api-keys': 'mountAPIKeys',
+    'oauth-consent': 'mountOAuthConsent',
   } as const satisfies Record<InternalUIComponentId, keyof Clerk>;
 
   Object.entries(mountFns).forEach(([category, mountFn]) => {
diff --git a/packages/astro/src/react/uiComponents.tsx b/packages/astro/src/react/uiComponents.tsx
@@ -1,5 +1,6 @@
 import type {
   GoogleOneTapProps,
+  OAuthConsentProps,
   OrganizationListProps,
   OrganizationProfileProps,
   OrganizationSwitcherProps,
@@ -196,3 +197,13 @@ export const PricingTable = withClerk(({ clerk, ...props }: WithClerkProp<Pricin
     />
   );
 }, 'PricingTable');
+
+export const OAuthConsent = withClerk(({ clerk, ...props }: WithClerkProp<OAuthConsentProps>) => {
+  return (
+    <Portal
+      mount={clerk?.mountOAuthConsent}
+      unmount={clerk?.unmountOAuthConsent}
+      props={props}
+    />
+  );
+}, 'OAuthConsent');
diff --git a/packages/astro/src/types.ts b/packages/astro/src/types.ts
@@ -119,4 +119,5 @@ export type InternalUIComponentId =
   | 'google-one-tap'
   | 'waitlist'
   | 'pricing-table'
-  | 'api-keys';
+  | 'api-keys'
+  | 'oauth-consent';
diff --git a/packages/clerk-js/sandbox/app.ts b/packages/clerk-js/sandbox/app.ts
@@ -475,7 +475,7 @@ void (async () => {
         description: scope === 'offline_access' ? null : `Grants access to your ${scope}`,
         requires_consent: true,
       }));
-      Clerk.__internal_mountOAuthConsent(
+      Clerk.mountOAuthConsent(
         app,
         componentControls.oauthConsent.getProps() ?? {
           scopes,
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
@@ -51,7 +51,7 @@ import type {
   __internal_AttemptToEnableEnvironmentSettingResult,
   __internal_CheckoutProps,
   __internal_EnableOrganizationsPromptProps,
-  __internal_OAuthConsentProps,
+  OAuthConsentProps,
   __internal_PlanDetailsProps,
   __internal_SubscriptionDetailsProps,
   __internal_UserVerificationModalProps,
@@ -1335,7 +1335,7 @@ export class Clerk implements ClerkInterface {
     void this.#clerkUI?.then(ui => ui.ensureMounted()).then(controls => controls.unmountComponent({ node }));
   };
 
-  public __internal_mountOAuthConsent = (node: HTMLDivElement, props?: __internal_OAuthConsentProps) => {
+  public mountOAuthConsent = (node: HTMLDivElement, props?: OAuthConsentProps) => {
     if (noUserExists(this)) {
       if (this.#instanceType === 'development') {
         throw new ClerkRuntimeError(warnings.cannotRenderOAuthConsentComponentWhenUserDoesNotExist, {
@@ -1359,7 +1359,7 @@ export class Clerk implements ClerkInterface {
       );
   };
 
-  public __internal_unmountOAuthConsent = (node: HTMLDivElement) => {
+  public unmountOAuthConsent = (node: HTMLDivElement) => {
     void this.#clerkUI?.then(ui => ui.ensureMounted()).then(controls => controls.unmountComponent({ node }));
   };
 
diff --git a/packages/nextjs/src/client-boundary/hooks.ts b/packages/nextjs/src/client-boundary/hooks.ts
@@ -4,6 +4,7 @@ export {
   useAuth,
   useClerk,
   useEmailLink,
+  useOAuthConsent,
   useOrganization,
   useOrganizationList,
   useOrganizationCreationDefaults,
diff --git a/packages/nextjs/src/client-boundary/uiComponents.tsx b/packages/nextjs/src/client-boundary/uiComponents.tsx
@@ -15,6 +15,8 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  HandleSSOCallback,
+  OAuthConsent,
   OrganizationList,
   OrganizationSwitcher,
   PricingTable,
@@ -28,11 +30,8 @@ export {
   UserAvatar,
   UserButton,
   Waitlist,
-  HandleSSOCallback,
 } from '@clerk/react';
 
-export { OAuthConsent } from '@clerk/react/internal';
-
 // The assignment of UserProfile with BaseUserProfile props is used
 // to support the CustomPage functionality (eg UserProfile.Page)
 // Also the `typeof BaseUserProfile` is used to resolve the following error:
diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts
@@ -25,6 +25,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationProfile,
   OrganizationSwitcher,
@@ -52,6 +53,7 @@ export {
   useAuth,
   useClerk,
   useEmailLink,
+  useOAuthConsent,
   useOrganization,
   useOrganizationCreationDefaults,
   useOrganizationList,
diff --git a/packages/nextjs/src/internal.ts b/packages/nextjs/src/internal.ts
@@ -3,5 +3,11 @@
  * If you do, app router will break.
  */
 export { MultisessionAppSupport } from './client-boundary/controlComponents';
+/**
+ * @deprecated Import `OAuthConsent` from `@clerk/nextjs` instead.
+ */
 export { OAuthConsent } from './client-boundary/uiComponents';
+/**
+ * @deprecated Import `useOAuthConsent` from `@clerk/nextjs` instead.
+ */
 export { useOAuthConsent } from '@clerk/shared/react';
diff --git a/packages/nuxt/src/runtime/components/index.ts b/packages/nuxt/src/runtime/components/index.ts
@@ -5,6 +5,7 @@ export {
   UserButton,
   OrganizationSwitcher,
   GoogleOneTap,
+  OAuthConsent,
   Waitlist,
   // Control components
   ClerkLoaded,
diff --git a/packages/react/src/components/index.ts b/packages/react/src/components/index.ts
@@ -2,6 +2,7 @@ export {
   APIKeys,
   CreateOrganization,
   GoogleOneTap,
+  OAuthConsent,
   OrganizationList,
   OrganizationProfile,
   OrganizationSwitcher,
diff --git a/packages/react/src/components/uiComponents.tsx b/packages/react/src/components/uiComponents.tsx
@@ -1,5 +1,5 @@
 import type {
-  __internal_OAuthConsentProps,
+  OAuthConsentProps,
   APIKeysProps,
   CreateOrganizationProps,
   GoogleOneTapProps,
@@ -645,7 +645,7 @@ export const APIKeys = withClerk(
 );
 
 export const OAuthConsent = withClerk(
-  ({ clerk, component, fallback, ...props }: WithClerkProp<__internal_OAuthConsentProps & FallbackProp>) => {
+  ({ clerk, component, fallback, ...props }: WithClerkProp<OAuthConsentProps & FallbackProp>) => {
     const mountingStatus = useWaitForComponentMount(component);
     const shouldShowFallback = mountingStatus === 'rendering' || !clerk.loaded;
 
@@ -659,8 +659,8 @@ export const OAuthConsent = withClerk(
         {clerk.loaded && (
           <ClerkHostRenderer
             component={component}
-            mount={clerk.__internal_mountOAuthConsent}
-            unmount={clerk.__internal_unmountOAuthConsent}
+            mount={clerk.mountOAuthConsent}
+            unmount={clerk.unmountOAuthConsent}
             updateProps={(clerk as any).__internal_updateProps}
             props={props}
             rootProps={rendererRootProps}
diff --git a/packages/react/src/hooks/index.ts b/packages/react/src/hooks/index.ts
@@ -11,6 +11,7 @@ export {
   useSession,
   useReverification,
   useAPIKeys,
+  useOAuthConsent,
   __experimental_useCheckout,
   __experimental_CheckoutProvider,
   __experimental_usePaymentElement,
diff --git a/packages/react/src/internal.ts b/packages/react/src/internal.ts
@@ -7,7 +7,14 @@ import type { ClerkProviderProps } from './types';
 
 export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
+/**
+ * @deprecated Import `useOAuthConsent` from `@clerk/react` instead.
+ */
 export { useOAuthConsent } from '@clerk/shared/react';
+
+/**
+ * @deprecated Import `OAuthConsent` from `@clerk/react` instead.
+ */
 export { OAuthConsent } from './components/uiComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
 export { useDerivedAuth } from './hooks/useAuth';
diff --git a/packages/react/src/isomorphicClerk.ts b/packages/react/src/isomorphicClerk.ts
@@ -6,7 +6,7 @@ import type {
   __internal_AttemptToEnableEnvironmentSettingResult,
   __internal_CheckoutProps,
   __internal_EnableOrganizationsPromptProps,
-  __internal_OAuthConsentProps,
+  OAuthConsentProps,
   __internal_PlanDetailsProps,
   __internal_SubscriptionDetailsProps,
   __internal_UserVerificationModalProps,
@@ -158,7 +158,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   private premountWaitlistNodes = new Map<HTMLDivElement, WaitlistProps | undefined>();
   private premountPricingTableNodes = new Map<HTMLDivElement, PricingTableProps | undefined>();
   private premountAPIKeysNodes = new Map<HTMLDivElement, APIKeysProps | undefined>();
-  private premountOAuthConsentNodes = new Map<HTMLDivElement, __internal_OAuthConsentProps | undefined>();
+  private premountOAuthConsentNodes = new Map<HTMLDivElement, OAuthConsentProps | undefined>();
   private premountTaskChooseOrganizationNodes = new Map<HTMLDivElement, TaskChooseOrganizationProps | undefined>();
   private premountTaskResetPasswordNodes = new Map<HTMLDivElement, TaskResetPasswordProps | undefined>();
   private premountTaskSetupMFANodes = new Map<HTMLDivElement, TaskSetupMFAProps | undefined>();
@@ -747,7 +747,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     });
 
     this.premountOAuthConsentNodes.forEach((props, node) => {
-      clerkjs.__internal_mountOAuthConsent(node, props);
+      clerkjs.mountOAuthConsent(node, props);
     });
 
     this.premountTaskChooseOrganizationNodes.forEach((props, node) => {
@@ -1282,17 +1282,17 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
   };
 
-  __internal_mountOAuthConsent = (node: HTMLDivElement, props?: __internal_OAuthConsentProps) => {
+  mountOAuthConsent = (node: HTMLDivElement, props?: OAuthConsentProps) => {
     if (this.clerkjs && this.loaded) {
-      this.clerkjs.__internal_mountOAuthConsent(node, props);
+      this.clerkjs.mountOAuthConsent(node, props);
     } else {
       this.premountOAuthConsentNodes.set(node, props);
     }
   };
 
-  __internal_unmountOAuthConsent = (node: HTMLDivElement) => {
+  unmountOAuthConsent = (node: HTMLDivElement) => {
     if (this.clerkjs && this.loaded) {
-      this.clerkjs.__internal_unmountOAuthConsent(node);
+      this.clerkjs.unmountOAuthConsent(node);
     } else {
       this.premountOAuthConsentNodes.delete(node);
     }
diff --git a/packages/shared/src/types/clerk.ts b/packages/shared/src/types/clerk.ts
@@ -667,14 +667,14 @@ export interface Clerk {
    * @param targetNode - Target node to mount the OAuth consent component.
    * @param oauthConsentProps - OAuth consent configuration parameters.
    */
-  __internal_mountOAuthConsent: (targetNode: HTMLDivElement, oauthConsentProps?: __internal_OAuthConsentProps) => void;
+  mountOAuthConsent: (targetNode: HTMLDivElement, oauthConsentProps?: OAuthConsentProps) => void;
 
   /**
    * Unmounts a OAuth consent component from the target element.
    *
    * @param targetNode - Target node to unmount the OAuth consent component from.
    */
-  __internal_unmountOAuthConsent: (targetNode: HTMLDivElement) => void;
+  unmountOAuthConsent: (targetNode: HTMLDivElement) => void;
 
   /**
    * Mounts a TaskChooseOrganization component at the target element.
@@ -2265,7 +2265,7 @@ export type __experimental_SubscriptionDetailsButtonProps = {
   };
 };
 
-export type __internal_OAuthConsentProps = {
+export type OAuthConsentProps = {
   /**
    * Customize the appearance of the component.
    */
diff --git a/packages/ui/src/components/OAuthConsent/__tests__/OAuthConsent.test.tsx b/packages/ui/src/components/OAuthConsent/__tests__/OAuthConsent.test.tsx
@@ -208,9 +208,9 @@ describe('OAuthConsent', () => {
       f.withUser({ email_addresses: ['jane@example.com'] });
     });
 
-    // Simulate the accounts portal path: `clerk.__internal_mountOAuthConsent` is
+    // Simulate the accounts portal path: `clerk.mountOAuthConsent` is
     // called with the legacy `oAuth*` (capital-A) prop shape from
-    // `__internal_OAuthConsentProps`. The `ComponentContextProvider` translates
+    // `OAuthConsentProps`. The `ComponentContextProvider` translates
     // these to the lowercase `oauth*` shape that the component reads from context
     // (see the `case 'OAuthConsent':` block in ClerkUIComponentsContext.tsx).
     // This test verifies the translation end-to-end: if it were broken, the
diff --git a/packages/ui/src/contexts/ClerkUIComponentsContext.tsx b/packages/ui/src/contexts/ClerkUIComponentsContext.tsx
diff --git a/packages/ui/src/types.ts b/packages/ui/src/types.ts
diff --git a/packages/vue/src/components/index.ts b/packages/vue/src/components/index.ts
diff --git a/packages/vue/src/components/ui-components/OAuthConsent.vue b/packages/vue/src/components/ui-components/OAuthConsent.vue
