feat(expo,clerk-js): core-3 expo compatibility

- Prevent DOM-based captcha from hanging in React Native environments
- Make expo-auth-session and expo-web-browser optional via dynamic imports
- Add SignedIn, SignedOut, and RedirectToTasks convenience components

Author: chriscanin

.changeset/core-3-expo-release.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/expo': patch
+---
+
+- Prevent DOM-based captcha from hanging in React Native environments
+- Make `expo-auth-session` and `expo-web-browser` optional via dynamic imports
+- Add `SignedIn`, `SignedOut`, and `RedirectToTasks` convenience components

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -81,6 +81,9 @@ export class CaptchaChallenge {
    * managed by clerk-js itself.
    */
   public async managedInModal(opts?: Partial<CaptchaOptions>) {
+    if (typeof document === 'undefined') {
+      return { captchaError: 'modal_component_not_ready' };
+    }
     return this.managedOrInvisible({
       modalWrapperQuerySelector: '#cl-modal-captcha-wrapper',
       modalContainerQuerySelector: '#cl-modal-captcha-container',

packages/expo/package.json

@@ -139,6 +139,9 @@
     "expo-apple-authentication": {
       "optional": true
     },
+    "expo-auth-session": {
+      "optional": true
+    },
     "expo-constants": {
       "optional": true
     },
@@ -150,6 +153,9 @@
     },
     "expo-secure-store": {
       "optional": true
+    },
+    "expo-web-browser": {
+      "optional": true
     }
   },
   "engines": {

packages/expo/src/components/controlComponents.tsx

@@ -1 +1,22 @@
-export { ClerkLoaded, ClerkLoading, Show } from '@clerk/react';
+// Re-export control components from @clerk/react
+// These provide conditional rendering based on auth state
+export { ClerkLoaded, ClerkLoading, RedirectToTasks, Show } from '@clerk/react';
+
+import { Show } from '@clerk/react';
+import type { PropsWithChildren, ReactNode } from 'react';
+
+/**
+ * Render children only when the user is signed in.
+ * A convenience wrapper around `<Show when="signed-in">`.
+ */
+export function SignedIn({ children }: PropsWithChildren): ReactNode {
+  return <Show when='signed-in'>{children}</Show>;
+}
+
+/**
+ * Render children only when the user is signed out.
+ * A convenience wrapper around `<Show when="signed-out">`.
+ */
+export function SignedOut({ children }: PropsWithChildren): ReactNode {
+  return <Show when='signed-out'>{children}</Show>;
+}

packages/expo/src/hooks/useOAuth.ts

@@ -1,7 +1,6 @@
 import { useSignIn, useSignUp } from '@clerk/react/legacy';
 import type { OAuthStrategy, SetActive, SignInResource, SignUpResource } from '@clerk/shared/types';
-import * as AuthSession from 'expo-auth-session';
-import * as WebBrowser from 'expo-web-browser';
+import type * as WebBrowser from 'expo-web-browser';
 
 import { errorThrower } from '../utils/errors';
 
@@ -46,6 +45,20 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
       };
     }
 
+    // Dynamically import expo-auth-session and expo-web-browser only when needed
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- dynamic import of optional dependency
+    let AuthSession: typeof import('expo-auth-session');
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- dynamic import of optional dependency
+    let WebBrowserModule: typeof import('expo-web-browser');
+    try {
+      [AuthSession, WebBrowserModule] = await Promise.all([import('expo-auth-session'), import('expo-web-browser')]);
+    } catch {
+      return errorThrower.throw(
+        'expo-auth-session and expo-web-browser are required for OAuth. ' +
+          'Install them: npx expo install expo-auth-session expo-web-browser',
+      );
+    }
+
     // Create a redirect url for the current platform and environment.
     //
     // This redirect URL needs to be whitelisted for your Clerk production instance via
@@ -64,7 +77,7 @@ export function useOAuth(useOAuthParams: UseOAuthFlowParams) {
 
     const { externalVerificationRedirectURL } = signIn.firstFactorVerification;
 
-    const authSessionResult = await WebBrowser.openAuthSessionAsync(
+    const authSessionResult = await WebBrowserModule.openAuthSessionAsync(
       // @ts-ignore
       externalVerificationRedirectURL.toString(),
       oauthRedirectUrl,

packages/expo/src/hooks/useSSO.ts

@@ -6,8 +6,7 @@ import type {
   SignInResource,
   SignUpResource,
 } from '@clerk/shared/types';
-import * as AuthSession from 'expo-auth-session';
-import * as WebBrowser from 'expo-web-browser';
+import type * as WebBrowser from 'expo-web-browser';
 
 import { errorThrower } from '../utils/errors';
 
@@ -48,6 +47,20 @@ export function useSSO() {
       };
     }
 
+    // Dynamically import expo-auth-session and expo-web-browser only when needed
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- dynamic import of optional dependency
+    let AuthSession: typeof import('expo-auth-session');
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- dynamic import of optional dependency
+    let WebBrowserModule: typeof import('expo-web-browser');
+    try {
+      [AuthSession, WebBrowserModule] = await Promise.all([import('expo-auth-session'), import('expo-web-browser')]);
+    } catch {
+      return errorThrower.throw(
+        'expo-auth-session and expo-web-browser are required for SSO. ' +
+          'Install them: npx expo install expo-auth-session expo-web-browser',
+      );
+    }
+
     const { strategy, unsafeMetadata, authSessionOptions } = startSSOFlowParams ?? {};
 
     /**
@@ -73,7 +86,7 @@ export function useSSO() {
       return errorThrower.throw('Missing external verification redirect URL for SSO flow');
     }
 
-    const authSessionResult = await WebBrowser.openAuthSessionAsync(
+    const authSessionResult = await WebBrowserModule.openAuthSessionAsync(
       externalVerificationRedirectURL.toString(),
       redirectUrl,
       authSessionOptions,

packages/expo/src/provider/singleton/createClerkInstance.ts

@@ -1,6 +1,6 @@
-import { type Clerk, isClerkRuntimeError } from '@clerk/clerk-js';
+import { type Clerk } from '@clerk/clerk-js';
 import type { BrowserClerk, HeadlessBrowserClerk } from '@clerk/react';
-import { is4xxError } from '@clerk/shared/error';
+import { is4xxError, isClerkRuntimeError } from '@clerk/shared/error';
 import type {
   ClientJSONSnapshot,
   EnvironmentJSONSnapshot,
@@ -62,7 +62,7 @@ export function createClerkInstance(ClerkClass: typeof Clerk) {
 
       const getToken = tokenCache.getToken;
       const saveToken = tokenCache.saveToken;
-      __internal_clerk = new ClerkClass(publishableKey);
+      __internal_clerk = new ClerkClass(publishableKey) as unknown as BrowserClerk;
 
       if (Platform.OS === 'ios' || Platform.OS === 'android') {
         // @ts-expect-error - This is an internal API
@@ -104,11 +104,13 @@ export function createClerkInstance(ClerkClass: typeof Clerk) {
         };
 
         if (createResourceCache) {
+          const isClerkNetworkError = (err: unknown): boolean =>
+            isClerkRuntimeError(err) && err.code === 'network_error';
+
           const retryInitilizeResourcesFromFAPI = async () => {
-            const isClerkNetworkError = (err: unknown) => isClerkRuntimeError(err) && err.code === 'network_error';
             try {
               await __internal_clerk?.__internal_reloadInitialResources();
-            } catch (err) {
+            } catch (err: unknown) {
               // Retry after 3 seconds if the error is a network error or a 5xx error
               if (isClerkNetworkError(err) || !is4xxError(err)) {
                 // Retry after 2 seconds if the error is a network error
@@ -123,9 +125,12 @@ export function createClerkInstance(ClerkClass: typeof Clerk) {
           ClientResourceCache.init({ publishableKey, storage: createResourceCache });
           SessionJWTCache.init({ publishableKey, storage: createResourceCache });
 
-          __internal_clerk.addListener(({ client }) => {
+          // At this point __internal_clerk is guaranteed to be defined (just created above)
+
+          const clerk = __internal_clerk;
+          clerk.addListener(({ client }) => {
             // @ts-expect-error - This is an internal API
-            const environment = __internal_clerk?.__internal_environment as EnvironmentResource;
+            const environment = clerk?.__internal_environment as EnvironmentResource;
             if (environment) {
               void EnvironmentResourceCache.save(environment.__internal_toSnapshot());
             }
@@ -144,7 +149,7 @@ export function createClerkInstance(ClerkClass: typeof Clerk) {
             }
           });
 
-          __internal_clerk.__internal_getCachedResources = async (): Promise<{
+          clerk.__internal_getCachedResources = async (): Promise<{
             client: ClientJSONSnapshot | null;
             environment: EnvironmentJSONSnapshot | null;
           }> => {

packages/expo/src/provider/singleton/singleton.web.ts

@@ -2,6 +2,13 @@ import type { BrowserClerk, HeadlessBrowserClerk } from '@clerk/react';
 
 import type { BuildClerkOptions } from './types';
 
+// Augment the global Window type to include Clerk
+declare global {
+  interface Window {
+    Clerk?: HeadlessBrowserClerk | BrowserClerk;
+  }
+}
+
 /**
  * Access the existing Clerk instance from `window.Clerk` on the web.
  * Unlike the native implementation, this does not create a new instance—it only returns the existing one set by ClerkProvider.