Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-expo

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

Add Clerk authentication to Expo and React Native apps using @clerk/expo. Use for Expo setup, prebuilt native components (AuthView, UserButton), custom sign-in/sign-up flows (email, password, SMS/phone OTP, MFA), OAuth/SSO, native Google/Apple sign-in, Expo Router protected routes, biometrics, and push notifications. Do not use for native Swift/iOS, native Android/Kotlin, or web-only framework projects.

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-expo

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈105 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈11k more on demand in 7 files.

Description uses 5.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈419 characters, or 5.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Clerk Expo (React Native)

Implement Clerk in Expo / React Native projects. This skill inlines verified patterns for the stable surface (provider, token cache, flows) and requires source inspection of the installed @clerk/expo package for anything volatile (component props, hook signatures).

Activation Rules

Activate when either is true:

  • The user asks for auth in an Expo or React Native app, or mentions @clerk/expo, ClerkProvider, Expo Router auth, or Clerk hooks in a native app.
  • The project is Expo/React Native (app.json / app.config.js, expo in package.json, metro.config.js, @clerk/expo dependency).

Route away when:

  • Native iOS/Swift project (.xcodeproj, Package.swift) → clerk-swift
  • Native Android/Kotlin project (build.gradle without React Native) → clerk-android
  • Web-only framework (Next.js, Remix, plain React, etc.) → the matching framework skill

Intent Map

Match what the user asked for, then load the reference(s) listed. Load only what the task needs.

User intent (examples) Path Reference
"Add auth to my app" / "add sign-in with Clerk" Prebuilt native components (default) references/setup.md + references/prebuilt-components.md
"Add auth" but Expo Go / web / custom UI required Custom flows references/setup.md + references/custom-flows.md
"Add phone / SMS auth", "email OTP", "passwordless" Custom flow, phoneCode / emailCode references/custom-flows.md
"Sign in with Google/Apple/GitHub", "social login", "SSO" Browser SSO or native buttons references/sso-and-native-auth.md
"MFA / 2FA / TOTP", "forgot password" Custom flow additions references/custom-flows.md
"Email link" Expo web custom flow; native apps use email codes for custom UI or <AuthView /> in a development build references/custom-flows.md + references/prebuilt-components.md
"Protect routes/screens", "redirect if signed out" Expo Router guards references/protected-routes.md
"Show user profile", "org switching", "push notifications", "sign out", "call my backend" App recipes references/recipes.md
"Biometric login", "Face ID", "passkeys" Device features references/recipes.md

Default Path Decision

When the user says "add auth" without specifying UI:

  1. Default to prebuilt native components (AuthView + UserButton from @clerk/expo/native). Fastest to working auth; UI is maintained by Clerk. Tell the developer they are in beta and require a development build.
  2. Fall back to custom flows when any of these hold — say why when you switch:
    • The project must run in Expo Go (no dev build).
    • The app targets web (native components don't render on web).
    • The developer wants their own UI or a specific brand experience beyond theming.
  3. If the developer has an existing auth UI, extend what's there — don't rip out custom flows to insert AuthView (or vice versa) without being asked.

Do not blend prebuilt components and custom flows for the same auth step (e.g. AuthView plus a custom password form). Blending is allowed only when the developer explicitly asks.

Quick Workflow

  1. Confirm project type (Expo/RN) and pick the path per the Intent Map / Default Path rules.
  2. For initial application setup, existing-app linking, or missing keys, follow the canonical clerk-setup skill. Don't start a separate init flow here. Then follow the Expo setup reference for provider, token cache, config plugin, and build-type steps not already completed.
  3. Verify dashboard prerequisites (Gate 2 and Gate 3 below).
  4. Implement from the selected reference only.
  5. Verify by building, not just by writing:
    • Run the project's typecheck (npx tsc --noEmit or equivalent).
    • Build and launch: npx expo run:ios / run:android for native features, npx expo start for Expo Go flows. If the build fails, fix and rebuild iteratively — build errors against the installed SDK are the ground truth when this skill and the SDK disagree. After ~5 failed fix attempts, stop and ask the developer how to proceed instead of thrashing.
    • Walk the developer through one real sign-in, then confirm the session survives an app restart (token cache working).

Execution Gates (Do Not Skip)

  1. Publishable key — Read from process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY in app code. Never NEXT_PUBLIC_, never hardcoded. If the key is missing, follow the appropriate new or existing application path in clerk-setup. Expo has no accountless keys, and an agent's init won't write one without a target application, even when signed in. For a new application, have the developer sign in and select or create an application, then run npx -y clerk@latest init --app <application_id>. For an existing application, have them sign in, link the selected application if needed, then run npx -y clerk@latest env pull. Alternatively, ask the developer for the publishable key from Clerk Dashboard → API keys and wait. Don't continue until a real key is set, and never run a fresh init for an existing Clerk project.
  2. Native API dashboard toggle — Clerk's Native API must be enabled for the instance: Clerk Dashboard → Native applications (https://dashboard.clerk.com/~/native-applications). Tell the developer to verify this during setup; it is required for any native integration.
  3. Factor availability — Before implementing a specific strategy (SMS, email code, social provider), confirm it's enabled for the instance. Derive the Frontend API URL from the publishable key (base64-decode the middle segment) and fetch <frontendApiUrl>/v1/environment?_is_native=true, or ask the developer to check the dashboard (User & authentication). SMS in particular is instance-configuration-dependent — code written for a disabled factor fails at runtime, not build time.
  4. Current custom-flows API only — useSignIn() / useSignUp() from @clerk/expo (v3.4+) return { signIn, errors, fetchStatus } and use method-based flows: signIn.password(), signIn.phoneCode.sendCode(), signIn.finalize(). Never generate the legacy pattern: destructuring isLoaded/setActive from useSignIn()/useSignUp() (the current hooks don't return them), or signIn.create() chained with prepareFirstFactor()/attemptFirstFactor() + setActive({ session }). That pattern lives at @clerk/expo/legacy and is only for maintaining existing legacy code, never for new work. Scope notes: isLoaded from useAuth()/useUser() is current API and required in guards; signIn.create() itself still exists for advanced cases — prefer the factor-specific methods.
  5. useSSO(), never useOAuth() — useOAuth is deprecated. Note the asymmetry: startSSOFlow() still returns { createdSessionId, setActive } and requires setActive({ session: createdSessionId }) — SSO does not use finalize().
  6. Token cache — tokenCache from @clerk/expo/token-cache on ClerkProvider. Never use expo-secure-store directly for session tokens, never AsyncStorage.
  7. resourceCache, never secureStore — if offline resource caching comes up, @clerk/expo/secure-store is deprecated; use resourceCache from @clerk/expo/resource-cache.
  8. Build-type gating — Native components (@clerk/expo/native) and native hooks (useSignInWithGoogle, useSignInWithApple, useLocalCredentials) require a development build (npx expo run:ios / run:android), not Expo Go, and don't exist on web. For web targets use @clerk/expo/web components or custom flows. State the build requirement before implementing a native-only feature.
  9. Combined sign-in-or-up default — one combined flow unless the developer asks for separate sign-in and sign-up screens.
  10. Bot protection — custom sign-up screens must render <View nativeID="clerk-captcha" />; Clerk's bot protection is on by default and needs this mount point.
  11. Source verification for volatile surfaces — before using native component props or native hook options, confirm against the installed package: node_modules/@clerk/expo/dist/native/*.d.ts and package.json exports. The installed version wins over this skill if they disagree.
  12. Freshness gate — this skill was verified against @clerk/expo 3.6.x. Check the installed version (node_modules/@clerk/expo/package.json). If it is a newer minor or major, treat this skill's code snippets as suspect: re-verify against the docs URL cited next to each snippet (every reference section carries one) or the installed .d.ts before using them. If it is older than 3.4, the method-based custom-flows API may not exist — offer an upgrade instead of writing legacy code.

Version Notes (v3.5–v3.6, June 2026)

  • Minimum React Native raised to 0.75 in v3.5.0 (iOS SDK now links via SPM podspec). Peer range: expo >=53 <57.
  • Native components matured: iOS moved to Expo Modules; native↔JS session sync is automatic and bidirectional — never call setActive() after native-component auth.
  • The config plugin accepts a theme JSON file for native component styling (see references/prebuilt-components.md).
  • Native Google sign-in will move to a separate @clerk/expo-google-signin package in the next major (the @clerk/expo/google import keeps working in v3; a dev warning announces the migration). Don't preinstall the new package on v3.

Common Pitfalls

Level Issue Prevention
CRITICAL Generating legacy custom-flow code (signIn.create + prepareFirstFactor + setActive) Use the current method-based API (Gate 4)
CRITICAL Using useOAuth() Use useSSO() (Gate 5)
CRITICAL Implementing SMS/social auth without checking the factor is enabled Check environment/dashboard first (Gate 3)
CRITICAL Native components targeted at Expo Go or web Require a dev build; offer custom flows otherwise (Gate 8)
CRITICAL Sign-up screen missing <View nativeID="clerk-captcha" /> Always include it (Gate 10)
HIGH NEXT_PUBLIC_ env prefix, or env var read inside node_modules EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY, passed explicitly to ClerkProvider
HIGH Session lost on restart tokenCache from @clerk/expo/token-cache on the provider
HIGH Calling setActive() after AuthView / UserButton auth Native components sync sessions automatically
HIGH Pairing AuthView with useSignInWithGoogle/useSignInWithApple AuthView renders enabled social providers itself
HIGH Calling WebBrowser.maybeCompleteAuthSession() manually ClerkProvider handles it
HIGH Splitting sign-in / sign-up without being asked Combined flow by default (Gate 9)
MEDIUM Missing isLoaded check before isSignedIn in guards Always gate on isLoaded first
MEDIUM Using yalc/pnpm link for local @clerk/expo development Use Verdaccio or pkg.pr.new

See Also

  • clerk — top-level router
  • clerk-swift / clerk-android — native mobile SDKs
  • clerk-orgs, clerk-billing, clerk-webhooks — feature skills (hooks work the same in Expo)
  • Installed package source: node_modules/@clerk/expo/
  • Expo quickstart
  • Expo SDK reference
  • Clerk Expo quickstart examples — three official example apps: JS-only (Expo Go), JS + native sign-in buttons, native components

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The clerk-expo skill is a development tool providing comprehensive patterns and instructions for integrating Clerk authentication into Expo and React Native applications. It covers installation, secure token management, prebuilt and custom UI flows, social authentication, and device-specific features like biometrics and push notifications. The analysis found no security issues or malicious intent; the skill follows official vendor practices and utilizes standard platform security features.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at 95f241a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
What it can do
Network
metadata
{
  "author": "clerk",
  "version": "2.0.2"
}
All 1 allowed tools
WebFetch
Other metadata
compatibility
Requires @clerk/expo v3.4+ (written against v3.6.x, July 2026). Expo SDK 53-56, React Native 0.75+.

README badge

README badge for clerk/skills/clerk-expo

Implements Clerk authentication in Expo and React Native projects using @clerk/expo, supporting either prebuilt AuthView/UserButton components or custom hook-driven flows. Handles ClerkProvider setup, token persistence, native sign-in strategies, and Expo config plugin registration—excludes native iOS/Swift, native Android/Kotlin, and web-only frameworks.

Generated from the current SKILL.md.

Does this skill work with native iOS/Swift or native Android/Kotlin projects?
No. This skill is for Expo and React Native only. Native iOS/Swift and native Android/Kotlin projects should use their respective Clerk SDKs, not this skill.
Do I need a development build or can I use Expo Go?
Native components like AuthView and UserButton require an iOS/Android development build. Expo Go does not support native modules. For web targets, use the @clerk/expo/web exports instead.
What's the difference between prebuilt and custom flows?
Prebuilt uses Clerk's AuthView or UserButton components for the fastest setup. Custom hook-driven flows give you full control over the UI and authentication state but require more implementation work.
Do I need to set the publishable key via environment variables?
No. Pass the publishable key directly to <ClerkProvider publishableKey={key}> unless you explicitly ask for environment-variable indirection. The skill will not introduce env-var wiring by default.
Does this skill cover Expo-specific recipes like token caching and protected routes?
This skill covers flow selection and end-to-end setup. Expo-specific recipes (SecureStore token cache, OAuth deep-link configuration, Expo Router protected routes) are in the clerk-expo-patterns skill instead.

Generated from the current SKILL.md. These answers refresh after source changes.