Update to Clerk

{
  "name": "clerk-expo",
  "description": "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.",
  "included_files": [
    {
      "relative_path": "evals/evals.json",
      "size_in_bytes": 6733
    },
    {
      "relative_path": "references/custom-flows.md",
      "size_in_bytes": 9526
    },
    {
      "relative_path": "references/prebuilt-components.md",
      "size_in_bytes": 5033
    },
    {
      "relative_path": "references/protected-routes.md",
      "size_in_bytes": 2550
    },
    {
      "relative_path": "references/recipes.md",
      "size_in_bytes": 5151
    },
    {
      "relative_path": "references/setup.md",
      "size_in_bytes": 5177
    },
    {
      "relative_path": "references/sso-and-native-auth.md",
      "size_in_bytes": 6171
    }
  ],
  "skill_md_contents": "---\nname: clerk-expo\ndescription: Add Clerk authentication to Expo and React Native apps using @clerk/expo.\n  Use for Expo setup, prebuilt native components (AuthView, UserButton), custom sign-in/sign-up\n  flows (email, password, SMS/phone OTP, MFA), OAuth/SSO, native Google/Apple sign-in,\n  Expo Router protected routes, biometrics, and push notifications. Do not use for\n  native Swift/iOS, native Android/Kotlin, or web-only framework projects.\nlicense: MIT\nallowed-tools: WebFetch\nmetadata:\n  author: clerk\n  version: 2.0.0\ncompatibility: Requires @clerk/expo v3.4+ (written against v3.6.x, July 2026). Expo SDK 53-56, React Native 0.75+.\n---\n\n# Clerk Expo (React Native)\n\nImplement 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).\n\n## Activation Rules\n\nActivate when either is true:\n- 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.\n- The project is Expo/React Native (`app.json` / `app.config.js`, `expo` in `package.json`, `metro.config.js`, `@clerk/expo` dependency).\n\nRoute away when:\n- Native iOS/Swift project (`.xcodeproj`, `Package.swift`) → `clerk-swift`\n- Native Android/Kotlin project (`build.gradle` without React Native) → `clerk-android`\n- Web-only framework (Next.js, Remix, plain React, etc.) → the matching framework skill\n\n## Intent Map\n\nMatch what the user asked for, then load the reference(s) listed. Load only what the task needs.\n\n| User intent (examples) | Path | Reference |\n|------------------------|------|-----------|\n| \"Add auth to my app\" / \"add sign-in with Clerk\" | Prebuilt native components (default) | references/setup.md + references/prebuilt-components.md |\n| \"Add auth\" but Expo Go / web / custom UI required | Custom flows | references/setup.md + references/custom-flows.md |\n| \"Add phone / SMS auth\", \"email OTP\", \"passwordless\" | Custom flow, `phoneCode` / `emailCode` | references/custom-flows.md |\n| \"Sign in with Google/Apple/GitHub\", \"social login\", \"SSO\" | Browser SSO or native buttons | references/sso-and-native-auth.md |\n| \"MFA / 2FA / TOTP\", \"forgot password\", \"email link\" | Custom flow additions | references/custom-flows.md |\n| \"Protect routes/screens\", \"redirect if signed out\" | Expo Router guards | references/protected-routes.md |\n| \"Show user profile\", \"org switching\", \"push notifications\", \"sign out\", \"call my backend\" | App recipes | references/recipes.md |\n| \"Biometric login\", \"Face ID\", \"passkeys\" | Device features | references/recipes.md |\n\n## Default Path Decision\n\nWhen the user says \"add auth\" without specifying UI:\n\n1. **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.\n2. **Fall back to custom flows** when any of these hold — say why when you switch:\n   - The project must run in Expo Go (no dev build).\n   - The app targets web (native components don't render on web).\n   - The developer wants their own UI or a specific brand experience beyond theming.\n3. 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.\n\nDo 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.\n\n## Quick Workflow\n\n1. Confirm project type (Expo/RN) and pick the path per the Intent Map / Default Path rules.\n2. Follow references/setup.md: install, env key, provider, token cache, config plugin, build type.\n3. Verify dashboard prerequisites (Gate 2 and Gate 3 below).\n4. Implement from the selected reference only.\n5. Verify by building, not just by writing:\n   - Run the project's typecheck (`npx tsc --noEmit` or equivalent).\n   - 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.\n   - Walk the developer through one real sign-in, then confirm the session survives an app restart (token cache working).\n\n## Execution Gates (Do Not Skip)\n\n1. **Publishable key** — Read from `process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` (`.env` file). Never `NEXT_PUBLIC_`, never hardcoded. If no key exists, ask the developer for one (or run `npx clerk@latest init --framework expo`, which installs the SDK and writes the env file) and wait before editing files.\n2. **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.\n3. **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.\n4. **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.\n5. **`useSSO()`, never `useOAuth()`** — `useOAuth` is deprecated. Note the asymmetry: `startSSOFlow()` still returns `{ createdSessionId, setActive }` and requires `setActive({ session: createdSessionId })` — SSO does not use `finalize()`.\n6. **Token cache** — `tokenCache` from `@clerk/expo/token-cache` on `ClerkProvider`. Never use `expo-secure-store` directly for session tokens, never AsyncStorage.\n7. **`resourceCache`, never `secureStore`** — if offline resource caching comes up, `@clerk/expo/secure-store` is deprecated; use `resourceCache` from `@clerk/expo/resource-cache`.\n8. **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.\n9. **Combined sign-in-or-up default** — one combined flow unless the developer asks for separate sign-in and sign-up screens.\n10. **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.\n11. **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.\n12. **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.\n\n## Version Notes (v3.5–v3.6, June 2026)\n\n- Minimum React Native raised to **0.75** in v3.5.0 (iOS SDK now links via SPM podspec). Peer range: `expo >=53 <57`.\n- Native components matured: iOS moved to Expo Modules; native↔JS session sync is automatic and bidirectional — never call `setActive()` after native-component auth.\n- The config plugin accepts a `theme` JSON file for native component styling (see references/prebuilt-components.md).\n- 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.\n\n## Common Pitfalls\n\n| Level | Issue | Prevention |\n|-------|-------|------------|\n| CRITICAL | Generating legacy custom-flow code (`signIn.create` + `prepareFirstFactor` + `setActive`) | Use the current method-based API (Gate 4) |\n| CRITICAL | Using `useOAuth()` | Use `useSSO()` (Gate 5) |\n| CRITICAL | Implementing SMS/social auth without checking the factor is enabled | Check environment/dashboard first (Gate 3) |\n| CRITICAL | Native components targeted at Expo Go or web | Require a dev build; offer custom flows otherwise (Gate 8) |\n| CRITICAL | Sign-up screen missing `<View nativeID=\"clerk-captcha\" />` | Always include it (Gate 10) |\n| HIGH | `NEXT_PUBLIC_` env prefix, or env var read inside `node_modules` | `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, passed explicitly to `ClerkProvider` |\n| HIGH | Session lost on restart | `tokenCache` from `@clerk/expo/token-cache` on the provider |\n| HIGH | Calling `setActive()` after `AuthView` / `UserButton` auth | Native components sync sessions automatically |\n| HIGH | Pairing `AuthView` with `useSignInWithGoogle`/`useSignInWithApple` | `AuthView` renders enabled social providers itself |\n| HIGH | Calling `WebBrowser.maybeCompleteAuthSession()` manually | `ClerkProvider` handles it |\n| HIGH | Splitting sign-in / sign-up without being asked | Combined flow by default (Gate 9) |\n| MEDIUM | Missing `isLoaded` check before `isSignedIn` in guards | Always gate on `isLoaded` first |\n| MEDIUM | Using `yalc`/`pnpm link` for local `@clerk/expo` development | Use Verdaccio or pkg.pr.new |\n\n## See Also\n\n- `clerk` — top-level router\n- `clerk-swift` / `clerk-android` — native mobile SDKs\n- `clerk-orgs`, `clerk-billing`, `clerk-webhooks` — feature skills (hooks work the same in Expo)\n- Installed package source: `node_modules/@clerk/expo/`\n- https://clerk.com/docs/getting-started/quickstart (Expo SDK tab)\n- https://clerk.com/docs/reference/expo/overview\n- https://github.com/clerk/clerk-expo-quickstart — three official example apps: JS-only (Expo Go), JS + native sign-in buttons, native components\n"
}