Clerk Expo

Clerk Expo (React Native)

This skill implements Clerk in Expo / React Native projects by inspecting the installed @clerk/expo package source and mirroring current hook and component behavior.

Activation Rules

Activate this skill when either condition is true:

• The user explicitly asks for Expo, React Native, @clerk/expo, ClerkProvider, or related Clerk component/hook implementation.
• The project appears to be Expo/React Native (for example app.json, app.config.js, metro.config.js, expo in package.json, @clerk/expo dependency).

Do not activate this skill when any condition is true:

• The project is native iOS/Swift (.xcodeproj, .xcworkspace, Package.swift, Swift targets).
• The project is native Android/Kotlin (build.gradle(.kts) with Android plugins, AndroidManifest.xml, no React Native).
• The project is a web-only framework (Next.js, Remix, etc.) without Expo/React Native.

If native iOS/Android or web-framework signals are present, route to the matching skill instead of this one.

Relationship to clerk-expo-patterns

This skill covers flow selection and end-to-end auth setup (prebuilt vs custom). The clerk-expo-patterns skill at skills/frameworks/clerk-expo-patterns/ covers Expo-specific recipes (SecureStore token cache, OAuth deep-link configuration, Expo Router protected routes, push notifications with user context). When both could apply, use this skill for the flow decision and overall setup, and load patterns from clerk-expo-patterns for the specific recipe.

What Do You Need?

Quick Start

Decision Tree

User asks for Clerk in Expo/React Native
    |
    +-- Native iOS/Android or web-framework project detected?
    |     |
    |     +-- YES -> Do not use this skill; route to matching skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Existing auth UI detected?
    |     |
    |     +-- Prebuilt AuthView/UserButton detected -> Load references/prebuilt.md
    |     |
    |     +-- Custom hook-based flow detected -> Load references/custom.md
    |     |
    |     +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
    |
    +-- Ensure publishable key and direct ClerkProvider wiring
    |
    +-- Ensure @clerk/expo is installed and Expo config plugin is registered
    |
    +-- Inspect installed @clerk/expo source for selected flow
    |
    +-- For custom flows: call /v1/environment?_is_native=true and build enabled-factor checklist
    |
    +-- Verify Expo quickstart prerequisites (token cache, dev build, peer deps)
    |
    +-- Implement using selected flow reference

Flow References

After flow type is known, load exactly one:

• Prebuilt flow: references/prebuilt.md
• Custom flow: references/custom.md

Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.

Interaction Contract

Before any implementation edits, the agent must have both:

• flow choice: prebuilt or custom
• a real Clerk publishable key (when setup/configuration is part of the task)

If either value is missing from the user request/context:

• ask the user for the missing value(s)
• pause and wait for the answer
• do not edit files or install dependencies yet

Only skip asking when the user has already explicitly provided the value in this conversation.

Source-Driven Templates

Do not hardcode implementation examples in this skill. Inspect installed @clerk/expo source for the project's installed version before implementing.

Execution Gates (Do Not Skip)

1. No implementation edits before prerequisites

• Do not edit project files until flow type is confirmed and (when setup is involved) a valid publishable key is available.

2. Missing flow or key must trigger a question

• If flow choice is missing, explicitly ask: prebuilt views or custom flow.
• If publishable key is missing/placeholder/invalid for a setup task, explicitly ask for a real key.
• Do not continue until required answers are provided.

3. Publishable key wiring mode is mandatory

• Pass the developer-provided publishable key directly to <ClerkProvider publishableKey={key}>.
• Do not introduce env-var indirection (process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY) unless the developer explicitly asks for it or the project follows the quickstart pattern.

4. Package install policy is mandatory

• If @clerk/expo is missing, install with npx expo install @clerk/expo.
• Install matching peer deps for the selected strategies (see prebuilt.md / custom.md for the per-flow list).
• Register the Expo config plugin in app.json / app.config.js: { "plugins": ["@clerk/expo"] }.

5. Custom-flow environment call is mandatory

• For custom flows: derive Frontend API URL from publishable key, fetch /v1/environment?_is_native=true, and use the response to determine enabled factors/strategies.
• Build an internal enabled-factor checklist; cover all enabled factors unless the developer explicitly narrows scope.
• Do not skip the environment call. Do not assume strategy coverage from convention.

6. Reference-file discipline is mandatory

• Once flow is selected, follow only that flow reference file for implementation and verification.

7. Hook-source-first discipline for custom flows

• Inspect installed @clerk/expo and @clerk/react hook source for response/error handling before deciding flow transitions.
• Mirror status-driven transitions from hook source rather than from UI heuristics or assumptions.

8. Combined sign-in-or-up default

• Implement one combined sign-in-or-up flow by default; do not split into separate sign-in / sign-up flows unless the developer explicitly requests separation.

9. Deprecated hook prohibition

• Never use useOAuth(). Always use useSSO() for OAuth and Enterprise SSO.

10. Platform / build gating

• Native components and native hooks (useSignInWithGoogle, useSignInWithApple, useNativeSession, useUserProfileModal, useLocalCredentials) require an iOS/Android development build, not Expo Go and not web.
• For web targets, use @clerk/expo/web exports.
• Always note platform availability before recommending native-only features.

11. Token cache discipline

• Use tokenCache from @clerk/expo/token-cache for persistent sessions; do not use expo-secure-store directly for token storage.

Workflow

1. Detect Expo/React Native vs native iOS/Android vs web framework. 2. If flow type is not explicitly provided, ask user for prebuilt or custom. 3. If publishable key is not explicitly provided for a setup task, ask user for it. 4. Wait for required answers before changing files. 5. Load the matching flow reference file. 6. Ensure <ClerkProvider> is at the app root with the publishable key wired directly and tokenCache from @clerk/expo/token-cache. 7. Ensure @clerk/expo is installed and the Expo config plugin is registered. Install peer deps for selected strategies. 8. Inspect installed @clerk/expo source for components/hooks relevant to the selected flow. 9. For custom flows: derive Frontend API URL from publishable key, call /v1/environment?_is_native=true, and build an internal enabled-factor checklist. 10. Verify Expo quickstart prerequisites (config plugin, token cache, native development build) and apply any missing required setup. 11. Implement using selected reference checklist. 12. For custom flows: verify implemented strategy coverage against the environment-derived checklist; close any missing enabled factor unless explicitly scoped out. 13. Verify using selected reference checklist plus shared gates.

Common Pitfalls

See Also

• clerk skill for top-level Clerk routing
• clerk-expo-patterns skill (skills/frameworks/clerk-expo-patterns/) for Expo-specific recipes (SecureStore token cache, OAuth deep links, Expo Router protected routes, push notifications)
• clerk-swift skill for native iOS implementation
• clerk-android skill for native Android implementation
• installed @clerk/expo package source (node_modules/@clerk/expo/)
• https://github.com/clerk/javascript/tree/main/packages/expo
• https://github.com/clerk/clerk-expo-quickstart
• https://clerk.com/docs/getting-started/quickstart (Expo SDK tab)
• https://clerk.com/docs/reference/expo/overview

Custom Flow Reference (@clerk/expo hooks)

Use this file only when flow type is custom.

Purpose

Implement Expo / React Native auth with @clerk/expo hooks (useSignIn, useSignUp, useSSO, native sign-in hooks) while preserving Clerk's status-driven, multi-step auth semantics.

Source-Driven Requirements

Use installed @clerk/expo package source as the primary reference:

• node_modules/@clerk/expo/dist/ (compiled JS)
• node_modules/@clerk/expo/src/ (TypeScript source if available)
• node_modules/@clerk/react/dist/ (re-exported hooks)
• node_modules/@clerk/shared/dist/ (shared utilities and error helpers)

Source priority rules for custom flow:

• Primary source: installed @clerk/expo and @clerk/react hook source for response/error handling, status fields, and flow transitions.
• Secondary source: clerk-expo-quickstart example app (https://github.com/clerk/clerk-expo-quickstart) for behavioral confirmation patterns.
• Fallback only: official Expo reference docs (https://clerk.com/docs/reference/expo/...) when behavior is unclear from source.

For custom flows, treat hook return values and status fields as the source of truth for auth transitions; do not infer transitions from UI heuristics.

Required Patterns

1. Package install

• If @clerk/expo is missing, install with npx expo install @clerk/expo.
• Install peer deps based on selected strategies:
• SSO/OAuth: npx expo install expo-auth-session expo-web-browser
• Persistent token cache: npx expo install expo-secure-store
• Native Apple sign-in (iOS): npx expo install expo-apple-authentication
• Biometric credentials: npx expo install expo-local-authentication expo-secure-store
• Add the Expo config plugin in app.json / app.config.js:

  { "plugins": ["@clerk/expo"] }

• Native hooks (useSignInWithGoogle, useSignInWithApple, useNativeSession, useUserProfileModal, useLocalCredentials) require a development build, not Expo Go.

2. ClerkProvider setup

• Wrap the app at the root with <ClerkProvider publishableKey={key} tokenCache={tokenCache}>.
• Pass the developer-provided publishable key directly; do not introduce env-var indirection unless explicitly requested or following the quickstart pattern.
• Use tokenCache from @clerk/expo/token-cache for persistent sessions.

3. Environment-driven strategy coverage

• Derive the Frontend API URL from the publishable key.
• Fetch environment at <frontendApiUrl>/v1/environment?_is_native=true before deciding strategy coverage.
• Treat the environment payload as the source of truth for enabled auth strategies/features.
• Build an internal enabled-factor checklist from the response and use it as the implementation coverage target.
• Implement support for all environment-enabled factors/strategies by default; ask only to narrow scope.
• If environment fetch fails, ask the developer which strategies to use and wait before continuing.
• Do not serialize the environment matrix into project source files.

4. Combined sign-in-or-up default

• Implement one combined sign-in-or-up flow by default.
• Do not split into separate sign-in and sign-up flows unless the developer explicitly requests separation.
• Handle fallback from sign-in to sign-up when identifier is not found:

  try {
    await signIn.create({ identifier });
  } catch (err) {
    if (isClerkAPIResponseError(err)) {
      const shouldSignUp = err.errors.some(e =>
        ['form_identifier_not_found', 'invitation_account_not_exists'].includes(e.code)
      );
      if (shouldSignUp) {
        await signUp.create({ emailAddress: identifier });
      } else {
        throw err;
      }
    }
  }

5. Status-driven multi-step progression

• Drive transitions from signIn.status and signUp.status returned by hook responses.
• Sign-in status values: needs_identifier, needs_first_factor, needs_second_factor, complete.
• Sign-up status values: missing_requirements, complete.
• On complete, call setActive({ session: result.createdSessionId }).
• Show only the inputs required by the current step; do not collect all fields up front.
• Mirror the response/error handling found in installed hook source for branching decisions.

6. Hook selection map

7. SSO / OAuth policy

• Always use useSSO() for OAuth and Enterprise SSO. Never use the deprecated useOAuth().
• redirectUrl defaults to AuthSession.makeRedirectUri({ path: 'sso-callback' }) if omitted.
• Treat user cancellation (authSessionResult.type !== 'success') as non-fatal; do not show error UI.
• useSSO internally clears stale session_exists cached JWT and retries; do not reimplement that.
• useSSO handles the transferable status by creating a sign-up with transfer: true; do not duplicate.
• Build provider option lists from environment-enabled providers, not hardcoded arrays.

8. Native Google / Apple policy

• Native Google: useSignInWithGoogle() from @clerk/expo/google. Requires Expo config plugin and EXPO_PUBLIC_CLERK_GOOGLE_IOS_URL_SCHEME. iOS + Android only.
• Native Apple: useSignInWithApple() from @clerk/expo/apple. Requires expo-apple-authentication and the Apple Sign In capability. iOS only.
• Provide a graceful fallback (e.g., useSSO({ strategy: 'oauth_google' / 'oauth_apple' })) on platforms where the native hook is unavailable.
• Do not implement provider-specific token exchange directly; always go through Clerk hooks.

9. Code organization and separation of concerns

• Split custom auth into focused modules:
• UI step screens / components per status state.
• Flow / state orchestration (hooks composing useSignIn + useSignUp).
• Strategy-specific glue (SSO entry, native sign-in entry, biometric setup).
• Keep module boundaries narrow so new factors/steps can be added without rewriting a monolithic screen.

10. Hook usage discipline

• Do not create custom auth state management when useAuth, useUser, useSession, useClerk already satisfy the need.
• Do not wrap Clerk hooks in unnecessary context providers or facades.
• Do not call WebBrowser.maybeCompleteAuthSession() manually; ClerkProvider does it.
• Do not use expo-secure-store directly for token caching; use @clerk/expo/token-cache.

Verification Checklist

1. Quickstart prerequisites are complete

• <ClerkProvider publishableKey={...} tokenCache={tokenCache}> is at the app root.
• Expo config plugin is registered.
• Required peer deps for selected strategies are installed.
• Native development build exists where native hooks are used.

2. Environment-driven coverage

• Frontend API URL was derived from the publishable key.
• /v1/environment?_is_native=true was called before strategy selection.
• Internal enabled-factor checklist exists and every factor is implemented (or explicitly out of scope per developer request).
• Environment matrix is not persisted in project source files.

3. Combined-flow default

• One combined sign-in-or-up flow is implemented; no split sign-in / sign-up unless explicitly requested.
• Identifier-not-found fallback into sign-up is implemented.

4. Status-driven transitions

• Transitions are driven by signIn.status / signUp.status returned from hook responses.
• Each step renders only the inputs required by the current status.
• setActive is called on complete with the resource's createdSessionId.

5. Hook discipline

• useSSO() is used for OAuth/Enterprise SSO; useOAuth() is never used.
• Native hooks are imported from sub-paths (@clerk/expo/google, /apple, /local-credentials).
• useAuth, useUser, useSession are used directly without redundant wrappers.

6. SSO behavior

• Cancellation is non-fatal; error UI only appears for true errors.
• transferable and session_exists are not re-implemented (handled inside useSSO).
• Provider lists are built from environment, not hardcoded.

7. Native sign-in correctness

• Native Google / Apple are used via their dedicated hooks where supported.
• Platform fallbacks via useSSO() exist where native hooks are unavailable.

8. Token persistence

• tokenCache from @clerk/expo/token-cache is configured; no direct expo-secure-store usage for token caching.

9. Architecture quality

• UI step screens, flow orchestration, and strategy-specific integration are split across focused files.

10. Source parity

• Hook response/error handling matches behavior found in installed @clerk/expo and @clerk/react source.

Prebuilt Flow Reference (@clerk/expo native components)

Use this file only when flow type is prebuilt.

Purpose

Implement Expo / React Native auth with prebuilt @clerk/expo native components (AuthView, UserButton, UserProfileView) instead of building custom hook-driven UI.

Note: native components are in beta per the Clerk Expo docs callout. Flag this to the developer before recommending them as the default for production rollout.

Required Patterns

1. Package install

• If @clerk/expo is missing, install with npx expo install @clerk/expo.
• Install peer dep expo-secure-store for persistent token cache (recommended).
• Add the Expo config plugin in app.json / app.config.js:

  { "plugins": ["@clerk/expo"] }

• Native components require a development build (expo run:ios / expo run:android); they do not work in Expo Go or on web.

2. Quickstart prerequisite audit

• Read the official Expo quickstart: https://clerk.com/docs/getting-started/quickstart (Expo SDK tab).
• Verify required project setup is present:
• <ClerkProvider publishableKey={...}> wraps the app at the root.
• tokenCache from @clerk/expo/token-cache is passed to <ClerkProvider> for session persistence.
• Expo config plugin is registered.
• Native build has been generated (npx expo prebuild or expo run:*).
• If required setup is missing, add it before finishing prebuilt auth implementation.

3. ClerkProvider setup

• Pass the developer-provided publishable key directly to <ClerkProvider publishableKey={key}>.
• Use tokenCache from @clerk/expo/token-cache for persistent sessions.
• IMPORTANT: set treatPendingAsSignedOut={false} for native-component apps so pending sessions are kept signed-in while AuthView/UserButton finish their flows. The Clerk docs call this out as required for native-component setups.

  import { ClerkProvider } from '@clerk/expo';
  import { tokenCache } from '@clerk/expo/token-cache';

  <ClerkProvider
    publishableKey={key}
    tokenCache={tokenCache}
    treatPendingAsSignedOut={false}
  >
    {/* app content */}
  </ClerkProvider>

• Do not set other ClerkProvider props that match defaults.
• Do not wrap ClerkProvider in custom context providers unless the developer has a specific requirement.
• ClerkProvider calls WebBrowser.maybeCompleteAuthSession() automatically; do not call it manually.

4. Imports

• All native components are imported from @clerk/expo/native:

  import { AuthView, UserButton, UserProfileView } from '@clerk/expo/native';

• The only public props on AuthView are mode and isDismissible. Do not pass onAuthEvent or other handlers — react to completion from useAuth() / useUser() / useSession() inside a useEffect instead.

5. Auth presentation pattern

• Default signed-out UI: <AuthView />. It renders inline in the parent container, so place it directly in your view hierarchy where you want the auth UI.
• Keep mode="signInOrUp" (the default combined behavior).
• Do not pass mode="signIn" or mode="signUp" unless the developer explicitly requests separate flows.
• Do not pair <AuthView /> with useSignInWithGoogle() or useSignInWithApple() — AuthView handles Google and Apple sign-in automatically when those providers are enabled. The Clerk docs are explicit about this.

6. Signed-in entry pattern

• Default signed-in entry: <UserButton /> (avatar + native profile modal).
• For inline profile management, use <UserProfileView />.
• For imperative modal presentation, use useUserProfileModal() from @clerk/expo.

7. Session synchronization

• Native components automatically sync auth state to the JS SDK; do not call setActive() after native component auth.
• Do not manually manage session state; ClerkProvider handles bidirectional sync via NativeSessionSync and useNativeAuthEvents internally.

8. Capability handling

• Provider availability and enabled factors are driven by environment configuration on the native side; do not hardcode provider lists in prebuilt mode.
• If a specific capability looks wrong, verify the Clerk Dashboard config rather than overriding the prebuilt UI.

9. Platform availability

• For web targets, use @clerk/expo/web control components or fall back to a hook-driven flow.

10. Minimal customization by default

• Do not replace prebuilt components with custom forms unless the developer asks for the custom flow.
• Keep customization focused on layout placement and theme integration.

Verification Checklist

1. Quickstart prerequisites are complete

• <ClerkProvider> is at the app root with the developer-provided publishable key wired directly.
• tokenCache from @clerk/expo/token-cache is configured.
• treatPendingAsSignedOut={false} is set on <ClerkProvider> (required for native-component apps).
• Expo config plugin is registered in app.json / app.config.js.
• Native development build exists (not Expo Go).
• Developer was informed that native components are in beta.

2. Default entry is prebuilt

• Signed-out state renders <AuthView /> placed inline in the view hierarchy.
• Signed-in state renders <UserButton /> or app content that includes it.

3. Default mode is combined

• <AuthView /> keeps default signInOrUp behavior; no sign-in-only or sign-up-only override unless explicitly requested.

4. No manual session management

• No manual setActive() calls after native component auth.
• No custom auth state management duplicating Clerk hooks.

5. Imports are correct

• Native components imported from @clerk/expo/native.
• Hooks for ancillary use (useAuth, useUser, useSession) imported from @clerk/expo.

6. Platform gating respected

• Native components are not used on web targets without a @clerk/expo/web fallback.
• Native development build is required for iOS/Android, not Expo Go.

7. No accidental custom-flow rewrite

• No unnecessary useSignIn / useSignUp form logic introduced alongside the prebuilt auth view.
• useSignInWithGoogle() / useSignInWithApple() are NOT used alongside <AuthView />; AuthView handles those providers internally.
• <AuthView /> is rendered without onAuthEvent or other non-public props.