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.

1. 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.

1. 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.

1. 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"] }.

1. 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.

1. Reference-file discipline is mandatory

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

1. 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.

1. 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.

1. Deprecated hook prohibition

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

1. 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.

1. 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