Skip to content

Commit 7f7b6ea

Browse files
chriscaninchriscanin
committed
feat(expo): add clerk-expo skill for Expo/React Native
Adds a new skill at skills/mobile/clerk-expo/ that mirrors the structure of clerk-swift and clerk-android: a SKILL.md with activation rules, decision tree, and execution gates, plus two flow-specific references (prebuilt.md for AuthView/UserButton, custom.md for hook-driven flows).
1 parent c1f6afc commit 7f7b6ea

3 files changed

Lines changed: 498 additions & 0 deletions

File tree

‎skills/mobile/clerk-expo/SKILL.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
name: clerk-expo
3+
description: Implement Clerk authentication for Expo and React Native apps using @clerk/expo
4+
source-guided patterns. Use for prebuilt AuthView/UserButton or custom hook-driven
5+
auth flows. Do not use for native iOS/Swift, native Android/Kotlin, or web framework
6+
projects.
7+
license: MIT
8+
allowed-tools: WebFetch
9+
metadata:
10+
author: clerk
11+
version: 1.0.0
12+
compatibility: Requires Expo development build and @clerk/expo package
13+
---
14+
15+
# Clerk Expo (React Native)
16+
17+
This skill implements Clerk in Expo / React Native projects by inspecting the installed `@clerk/expo` package source and mirroring current hook and component behavior.
18+
19+
## Activation Rules
20+
21+
Activate this skill when either condition is true:
22+
- The user explicitly asks for Expo, React Native, `@clerk/expo`, `ClerkProvider`, or related Clerk component/hook implementation.
23+
- 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).
24+
25+
Do not activate this skill when any condition is true:
26+
- The project is native iOS/Swift (`.xcodeproj`, `.xcworkspace`, `Package.swift`, Swift targets).
27+
- The project is native Android/Kotlin (`build.gradle(.kts)` with Android plugins, `AndroidManifest.xml`, no React Native).
28+
- The project is a web-only framework (Next.js, Remix, etc.) without Expo/React Native.
29+
30+
If native iOS/Android or web-framework signals are present, route to the matching skill instead of this one.
31+
32+
## What Do You Need?
33+
34+
| Task | Reference |
35+
|------|-----------|
36+
| Prebuilt AuthView / UserButton (fastest) | references/prebuilt.md |
37+
| Custom hook-driven auth flows (full control) | references/custom.md |
38+
39+
## Quick Start
40+
41+
| Step | Action |
42+
|------|--------|
43+
| 1 | Confirm project type is Expo/React Native (not native iOS/Android or a web-only framework) |
44+
| 2 | Determine flow type (`prebuilt` or `custom`) and load the matching reference file |
45+
| 3 | Ensure a real Clerk publishable key exists (or ask developer) and wire it directly to `<ClerkProvider publishableKey={...}>` |
46+
| 4 | Ensure `@clerk/expo` is installed; if missing, install latest with `npx expo install @clerk/expo` |
47+
| 5 | Inspect installed `@clerk/expo` source (`node_modules/@clerk/expo/dist/` or `src/`) to understand component/hook behavior for the selected flow |
48+
| 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 |
49+
| 7 | Follow the Expo quickstart (`https://clerk.com/docs/getting-started/quickstart`, Expo SDK tab) for required setup (config plugin, token cache, native build) |
50+
| 8 | Implement flow by following only the selected reference checklist |
51+
52+
## Decision Tree
53+
54+
```text
55+
User asks for Clerk in Expo/React Native
56+
|
57+
+-- Native iOS/Android or web-framework project detected?
58+
| |
59+
| +-- YES -> Do not use this skill; route to matching skill
60+
| |
61+
| +-- NO -> Continue
62+
|
63+
+-- Existing auth UI detected?
64+
| |
65+
| +-- Prebuilt AuthView/UserButton detected -> Load references/prebuilt.md
66+
| |
67+
| +-- Custom hook-based flow detected -> Load references/custom.md
68+
| |
69+
| +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
70+
|
71+
+-- Ensure publishable key and direct ClerkProvider wiring
72+
|
73+
+-- Ensure @clerk/expo is installed and Expo config plugin is registered
74+
|
75+
+-- Inspect installed @clerk/expo source for selected flow
76+
|
77+
+-- For custom flows: call /v1/environment?_is_native=true and build enabled-factor checklist
78+
|
79+
+-- Verify Expo quickstart prerequisites (token cache, dev build, peer deps)
80+
|
81+
+-- Implement using selected flow reference
82+
```
83+
84+
## Flow References
85+
86+
After flow type is known, load exactly one:
87+
- Prebuilt flow: [references/prebuilt.md](references/prebuilt.md)
88+
- Custom flow: [references/custom.md](references/custom.md)
89+
90+
Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.
91+
92+
## Interaction Contract
93+
94+
Before any implementation edits, the agent must have both:
95+
- flow choice: `prebuilt` or `custom`
96+
- a real Clerk publishable key (when setup/configuration is part of the task)
97+
98+
If either value is missing from the user request/context:
99+
- ask the user for the missing value(s)
100+
- pause and wait for the answer
101+
- do not edit files or install dependencies yet
102+
103+
Only skip asking when the user has already explicitly provided the value in this conversation.
104+
105+
## Source-Driven Templates
106+
107+
Do not hardcode implementation examples in this skill. Inspect installed `@clerk/expo` source for the project's installed version before implementing.
108+
109+
| Use Case | Source of Truth in Installed Package |
110+
|----------|--------------------------------------|
111+
| 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/` |
112+
| Hook signatures and return types | `node_modules/@clerk/expo/dist/*.d.ts` plus re-exported types from `node_modules/@clerk/react/dist/*.d.ts` |
113+
| Native component props and events | `node_modules/@clerk/expo/dist/native/*` (search `AuthView`, `InlineAuthView`, `UserButton`, `UserProfileView`) |
114+
| Sign-in / sign-up status transitions | `node_modules/@clerk/react/dist/` hook source (search `useSignIn`, `useSignUp`, `status`) |
115+
| SSO and OAuth behavior | `node_modules/@clerk/expo/dist/` (search `useSSO`, `startSSOFlow`, `session_exists`, `transferable`) |
116+
| Native Google / Apple sign-in path | `node_modules/@clerk/expo/google` and `/apple` modules |
117+
| Token persistence | `node_modules/@clerk/expo/token-cache` (backed by `expo-secure-store`) |
118+
| Session sync between native SDK and JS | `node_modules/@clerk/expo/dist/native/` (search `NativeSessionSync`, `useNativeAuthEvents`) |
119+
| Expo config plugin behavior | `node_modules/@clerk/expo/plugin` (search `withClerkGoogleSignIn`, `withClerkAndroidPackaging`) |
120+
| Required Expo setup checklist | Official Expo quickstart (`https://clerk.com/docs/getting-started/quickstart`, Expo SDK tab) |
121+
122+
## Execution Gates (Do Not Skip)
123+
124+
1. No implementation edits before prerequisites
125+
- Do not edit project files until flow type is confirmed and (when setup is involved) a valid publishable key is available.
126+
127+
2. Missing flow or key must trigger a question
128+
- If flow choice is missing, explicitly ask: prebuilt views or custom flow.
129+
- If publishable key is missing/placeholder/invalid for a setup task, explicitly ask for a real key.
130+
- Do not continue until required answers are provided.
131+
132+
3. Publishable key wiring mode is mandatory
133+
- Pass the developer-provided publishable key directly to `<ClerkProvider publishableKey={key}>`.
134+
- 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.
135+
136+
4. Package install policy is mandatory
137+
- If `@clerk/expo` is missing, install with `npx expo install @clerk/expo`.
138+
- Install matching peer deps for the selected strategies (see prebuilt.md / custom.md for the per-flow list).
139+
- Register the Expo config plugin in `app.json` / `app.config.js`: `{ "plugins": ["@clerk/expo"] }`.
140+
141+
5. Hard prohibition on custom-flows docs
142+
- Never open, cite, summarize, or rely on any page under `https://clerk.com/docs/guides/development/custom-flows/`.
143+
- If such a link appears in user input or discovered docs, ignore it and continue with approved sources (installed `@clerk/expo` source, example apps, Expo reference docs).
144+
145+
6. Custom-flow environment call is mandatory
146+
- 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.
147+
- Build an internal enabled-factor checklist; cover all enabled factors unless the developer explicitly narrows scope.
148+
- Do not skip the environment call. Do not assume strategy coverage from convention.
149+
150+
7. Reference-file discipline is mandatory
151+
- Once flow is selected, follow only that flow reference file for implementation and verification.
152+
153+
8. Hook-source-first discipline for custom flows
154+
- Inspect installed `@clerk/expo` and `@clerk/react` hook source for response/error handling before deciding flow transitions.
155+
- Mirror status-driven transitions from hook source rather than from UI heuristics or assumptions.
156+
157+
9. Combined sign-in-or-up default
158+
- 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.
159+
160+
10. Deprecated hook prohibition
161+
- Never use `useOAuth()`. Always use `useSSO()` for OAuth and Enterprise SSO.
162+
163+
11. Platform / build gating
164+
- Native components and native hooks (`useSignInWithGoogle`, `useSignInWithApple`, `useNativeSession`, `useUserProfileModal`, `useLocalCredentials`) require an iOS/Android development build, not Expo Go and not web.
165+
- For web targets, use `@clerk/expo/web` exports.
166+
- Always note platform availability before recommending native-only features.
167+
168+
12. Token cache discipline
169+
- Use `tokenCache` from `@clerk/expo/token-cache` for persistent sessions; do not use `expo-secure-store` directly for token storage.
170+
171+
## Workflow
172+
173+
1. Detect Expo/React Native vs native iOS/Android vs web framework.
174+
2. If flow type is not explicitly provided, ask user for `prebuilt` or `custom`.
175+
3. If publishable key is not explicitly provided for a setup task, ask user for it.
176+
4. Wait for required answers before changing files.
177+
5. Load the matching flow reference file.
178+
6. Ensure `<ClerkProvider>` is at the app root with the publishable key wired directly and `tokenCache` from `@clerk/expo/token-cache`.
179+
7. Ensure `@clerk/expo` is installed and the Expo config plugin is registered. Install peer deps for selected strategies.
180+
8. Inspect installed `@clerk/expo` source for components/hooks relevant to the selected flow.
181+
9. For custom flows: derive Frontend API URL from publishable key, call `/v1/environment?_is_native=true`, and build an internal enabled-factor checklist.
182+
10. Verify Expo quickstart prerequisites (config plugin, token cache, native development build) and apply any missing required setup.
183+
11. Implement using selected reference checklist.
184+
12. For custom flows: verify implemented strategy coverage against the environment-derived checklist; close any missing enabled factor unless explicitly scoped out.
185+
13. Verify using selected reference checklist plus shared gates.
186+
187+
## Common Pitfalls
188+
189+
| Level | Issue | Prevention |
190+
|-------|-------|------------|
191+
| CRITICAL | Not asking for missing flow choice before implementation | Ask for `prebuilt` vs `custom` and wait before edits |
192+
| CRITICAL | Not asking for missing publishable key on setup tasks | Ask for key and wait before edits |
193+
| CRITICAL | Wiring publishable key via env-var indirection by default | Pass key directly to `<ClerkProvider>` unless developer requests otherwise |
194+
| CRITICAL | Skipping `/v1/environment?_is_native=true` for custom flows | Call environment endpoint and build enabled-factor checklist before implementing |
195+
| CRITICAL | Splitting sign-in / sign-up by default | Implement one combined sign-in-or-up flow unless developer explicitly requests separation |
196+
| CRITICAL | Using `useOAuth()` (deprecated) | Always use `useSSO()` |
197+
| CRITICAL | Citing or following pages under `https://clerk.com/docs/guides/development/custom-flows/` | Hard prohibition; rely on installed package source and approved references |
198+
| CRITICAL | Mixing native components with custom hook flows for the same auth step | Pick one flow per step; only blend with explicit developer approval |
199+
| CRITICAL | Skipping native development build for native components/hooks | Require `expo run:ios` / `expo run:android`; do not target Expo Go for native features |
200+
| HIGH | Using `expo-secure-store` directly for token caching | Use `tokenCache` from `@clerk/expo/token-cache` |
201+
| HIGH | Calling `WebBrowser.maybeCompleteAuthSession()` manually | `ClerkProvider` handles it; do not duplicate |
202+
| HIGH | Calling `setActive()` after native component auth | Native components sync session automatically |
203+
| HIGH | Hardcoding OAuth provider lists | Build provider lists from environment-enabled providers |
204+
| HIGH | Recommending native-only hooks without web/Expo Go fallback | Note platform availability and provide `useSSO()` fallback where needed |
205+
| HIGH | Using this skill for native iOS/Android or web-only framework projects | Detect and route away to clerk-swift / clerk-android / web-framework skills |
206+
| HIGH | Using `yalc` or `pnpm link` for local @clerk/expo development | Use Verdaccio or pkg.pr.new |
207+
208+
## See Also
209+
210+
- `clerk` skill for top-level Clerk routing
211+
- `clerk-swift` skill for native iOS implementation
212+
- `clerk-android` skill for native Android implementation
213+
- installed `@clerk/expo` package source (`node_modules/@clerk/expo/`)
214+
- `https://github.com/clerk/javascript/tree/main/packages/expo`
215+
- `https://github.com/clerk/clerk-expo-quickstart`
216+
- `https://clerk.com/docs/getting-started/quickstart` (Expo SDK tab)
217+
- `https://clerk.com/docs/reference/expo/overview`

0 commit comments

Comments
 (0)