clerk-expo

What this skill does

# 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?

| Task | Reference |
|------|-----------|
| Prebuilt AuthView / UserButton (fastest) | references/prebuilt.md |
| Custom hook-driven auth flows (full control) | references/custom.md |

## Quick Start

| Step | Action |
|------|--------|
| 1 | Confirm project type is Expo/React Native (not native iOS/Android or a web-only framework) |
| 2 | Determine flow type (`prebuilt` or `custom`) and load the matching reference file |
| 3 | Ensure a real Clerk publishable key exists (or ask developer) and wire it directly to `<ClerkProvider publishableKey={...}>` |
| 4 | Ensure `@clerk/expo` is installed; if missing, install latest with `npx expo install @clerk/expo` |
| 5 | Inspect installed `@clerk/expo` source (`node_modules/@clerk/expo/dist/` or `src/`) to understand component/hook behavior for the selected flow |
| 6 | For custom flows: derive Frontend API URL from publishable key, then call `<frontendApiUrl>/v1/environment?_is_native=true` and build an internal enabled-factor checklist |
| 7 | Follow the Expo quickstart (`https://clerk.com/docs/getting-started/quickstart`, Expo SDK tab) for required setup (config plugin, token cache, native build) |
| 8 | Implement flow by following only the selected reference checklist |

## Decision Tree

```text
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](references/prebuilt.md)
- Custom flow: [references/custom.md](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.

| Use Case | Source of Truth in Installed Package |
|----------|--------------------------------------|
| Package exports and sub-paths (`@clerk/expo/google`, `/apple`, `/native`, `/token-cache`, `/local-credentials`, `/resource-cache`, `/web`) | `node_modules/@clerk/expo/package.json` `exports` field plus compiled output in `dist/` |
| Hook signatures and return types | `node_modules/@clerk/expo/dist/*.d.ts` plus re-exported types from `node_modules/@clerk/react/dist/*.d.ts` |
| Native component props and events | `node_modules/@clerk/expo/dist/native/*` (search `AuthView`, `InlineAuthView`, `UserButton`, `UserProfileView`) |
| Sign-in / sign-up status transitions | `node_modules/@clerk/react/dist/` hook source (search `useSignIn`, `useSignUp`, `status`) |
| SSO and OAuth behavior | `node_modules/@clerk/expo/dist/` (search `useSSO`, `startSSOFlow`, `session_exists`, `transferable`) |
| Native Google / Apple sign-in path | `node_modules/@clerk/expo/google` and `/apple` modules |
| Token persistence | `node_modules/@clerk/expo/token-cache` (backed by `expo-secure-store`) |
| Session sync between native SDK and JS | `node_modules/@clerk/expo/dist/native/` (search `NativeSessionSync`, `useNativeAuthEvents`) |
| Expo config plugin behavior | `node_modules/@clerk/expo/app.plugin.js` (search `withClerkGoogleSignIn`, `withClerkAndroidPackaging`) |
| Required Expo setup checklist | Official Expo quickstart (`https://clerk.com/docs/getting-started/quickstart`, Expo SDK tab) |

## 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 an