clerk-expo
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseClerk Expo (React Native)
Clerk Expo(React Native)
This skill implements Clerk in Expo / React Native projects by inspecting the installed package source and mirroring current hook and component behavior.
@clerk/expo本技能通过检查已安装的包源码并镜像当前钩子和组件的行为,在Expo/React Native项目中实现Clerk身份验证。
@clerk/expoActivation Rules
激活规则
Activate this skill when either condition is true:
- The user explicitly asks for Expo, React Native, ,
@clerk/expo, or related Clerk component/hook implementation.ClerkProvider - The project appears to be Expo/React Native (for example ,
app.json,app.config.js,metro.config.jsinexpo,package.jsondependency).@clerk/expo
Do not activate this skill when any condition is true:
- The project is native iOS/Swift (,
.xcodeproj,.xcworkspace, Swift targets).Package.swift - The project is native Android/Kotlin (with Android plugins,
build.gradle(.kts), no React Native).AndroidManifest.xml - 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.
当满足以下任一条件时激活本技能:
- 用户明确询问Expo、React Native、、
@clerk/expo或相关Clerk组件/钩子的实现方法。ClerkProvider - 项目看起来是Expo/React Native类型(例如存在、
app.json、app.config.js,metro.config.js中有package.json或expo依赖)。@clerk/expo
当满足以下任一条件时请勿激活本技能:
- 项目是原生iOS/Swift类型(存在、
.xcodeproj、.xcworkspace、Swift目标文件)。Package.swift - 项目是原生Android/Kotlin类型(存在带Android插件的、
build.gradle(.kts),无React Native相关内容)。AndroidManifest.xml - 项目是纯Web框架(Next.js、Remix等)且不包含Expo/React Native。
如果检测到原生iOS/Android或Web框架的特征,请将请求路由到对应的技能,而非本技能。
Relationship to clerk-expo-patterns
clerk-expo-patterns与clerk-expo-patterns
的关系
clerk-expo-patternsThis skill covers flow selection and end-to-end auth setup (prebuilt vs custom). The skill at 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 for the specific recipe.
clerk-expo-patternsskills/frameworks/clerk-expo-patterns/clerk-expo-patterns本技能涵盖流程选择和端到端身份验证设置(预构建 vs 自定义)。位于的技能则涵盖Expo特定的方案(SecureStore令牌缓存、OAuth深度链接配置、Expo Router受保护路由、带用户上下文的推送通知)。当两个技能都适用时,使用本技能进行流程决策和整体设置,并从加载特定方案的模式。
skills/frameworks/clerk-expo-patterns/clerk-expo-patternsclerk-expo-patternsWhat Do You Need?
所需资源
| Task | Reference |
|---|---|
| Prebuilt AuthView / UserButton (fastest) | references/prebuilt.md |
| Custom hook-driven auth flows (full control) | references/custom.md |
| 任务 | 参考文档 |
|---|---|
| 预构建AuthView / UserButton(最快实现) | references/prebuilt.md |
| 自定义钩子驱动的身份验证流程(完全可控) | 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 ( |
| 3 | Ensure a real Clerk publishable key exists (or ask developer) and wire it directly to |
| 4 | Ensure |
| 5 | Inspect installed |
| 6 | For custom flows: derive Frontend API URL from publishable key, then call |
| 7 | Follow the Expo quickstart ( |
| 8 | Implement flow by following only the selected reference checklist |
| 步骤 | 操作 |
|---|---|
| 1 | 确认项目类型为Expo/React Native(而非原生iOS/Android或纯Web框架) |
| 2 | 确定流程类型( |
| 3 | 确保存在有效的Clerk发布密钥(或向开发者索要),并直接将其传入 |
| 4 | 确保已安装 |
| 5 | 检查已安装的 |
| 6 | 对于自定义流程:从发布密钥推导Frontend API URL,调用 |
| 7 | 遵循Expo快速开始指南( |
| 8 | 仅遵循所选参考文件的清单实现流程 |
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 referencetext
用户询问Expo/React Native中的Clerk实现
|
+-- 检测到原生iOS/Android或Web框架项目?
| |
| +-- 是 -> 不使用本技能;路由到对应技能
| |
| +-- 否 -> 继续
|
+-- 检测到现有身份验证UI?
| |
| +-- 检测到预构建AuthView/UserButton -> 加载references/prebuilt.md
| |
| +-- 检测到自定义钩子流程 -> 加载references/custom.md
| |
| +-- 全新实现 -> 询问开发者选择预构建还是自定义,然后加载对应参考文件
|
+-- 确保发布密钥已配置并直接传入ClerkProvider
|
+-- 确保@clerk/expo已安装且Expo配置插件已注册
|
+-- 检查所选流程对应的@clerk/expo源码
|
+-- 对于自定义流程:调用/v1/environment?_is_native=true并构建启用因素清单
|
+-- 验证Expo快速开始的先决条件(令牌缓存、开发构建、依赖项)
|
+-- 使用所选流程参考文件实现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.
确定流程类型后,仅加载以下其中一个:
- 预构建流程:references/prebuilt.md
- 自定义流程:references/custom.md
除非开发者明确要求混合实现,否则请勿在单次实现中混用两个参考文件的内容。
Interaction Contract
交互约定
Before any implementation edits, the agent must have both:
- flow choice: or
prebuiltcustom - 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.
在进行任何实现编辑之前,智能代理必须同时具备:
- 流程选择:或
prebuiltcustom - 有效的Clerk发布密钥(当设置/配置是任务的一部分时)
如果用户请求/上下文中缺少任一值:
- 向用户询问缺失的值
- 暂停并等待回复
- 暂不编辑文件或安装依赖
仅当用户在本次对话中已明确提供对应值时,才可跳过询问步骤。
Source-Driven Templates
源码驱动模板
Do not hardcode implementation examples in this skill. Inspect installed source for the project's installed version before implementing.
@clerk/expo| Use Case | Source of Truth in Installed Package |
|---|---|
Package exports and sub-paths ( | |
| Hook signatures and return types | |
| Native component props and events | |
| Sign-in / sign-up status transitions | |
| SSO and OAuth behavior | |
| Native Google / Apple sign-in path | |
| Token persistence | |
| Session sync between native SDK and JS | |
| Expo config plugin behavior | |
| Required Expo setup checklist | Official Expo quickstart ( |
请勿在本技能中硬编码实现示例。在实现前,请检查项目中已安装的版本的源码。
@clerk/expo| 使用场景 | 已安装包中的事实来源 |
|---|---|
包导出和子路径( | |
| 钩子签名和返回类型 | |
| 原生组件属性和事件 | |
| 登录/注册状态转换 | |
| SSO和OAuth行为 | |
| 原生Google/Apple登录路径 | |
| 令牌持久化 | |
| 原生SDK与JS之间的会话同步 | |
| Expo配置插件行为 | |
| 必要的Expo设置清单 | 官方Expo快速开始指南( |
Execution Gates (Do Not Skip)
执行限制(请勿跳过)
- 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.
- 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.
- Publishable key wiring mode is mandatory
- Pass the developer-provided publishable key directly to .
<ClerkProvider publishableKey={key}> - Do not introduce env-var indirection () unless the developer explicitly asks for it or the project follows the quickstart pattern.
process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY
- Package install policy is mandatory
- If is missing, install with
@clerk/expo.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"] }
- Custom-flow environment call is mandatory
- For custom flows: derive Frontend API URL from publishable key, fetch , and use the response to determine enabled factors/strategies.
/v1/environment?_is_native=true - 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.
- Reference-file discipline is mandatory
- Once flow is selected, follow only that flow reference file for implementation and verification.
- Hook-source-first discipline for custom flows
- Inspect installed and
@clerk/expohook source for response/error handling before deciding flow transitions.@clerk/react - Mirror status-driven transitions from hook source rather than from UI heuristics or assumptions.
- 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.
- Deprecated hook prohibition
- Never use . Always use
useOAuth()for OAuth and Enterprise SSO.useSSO()
- Platform / build gating
- Native components and native hooks (,
useSignInWithGoogle,useSignInWithApple,useNativeSession,useUserProfileModal) require an iOS/Android development build, not Expo Go and not web.useLocalCredentials - For web targets, use exports.
@clerk/expo/web - Always note platform availability before recommending native-only features.
- Token cache discipline
- Use from
tokenCachefor persistent sessions; do not use@clerk/expo/token-cachedirectly for token storage.expo-secure-store
- 完成先决条件前不得进行实现编辑
- 在确认流程类型且(当涉及设置时)获得有效的发布密钥之前,请勿编辑项目文件。
- 缺失流程或密钥必须触发询问
- 如果缺少流程选择,明确询问:使用预构建视图还是自定义流程。
- 如果设置任务中缺少发布密钥/密钥为占位符/无效,明确索要有效的密钥。
- 在获得所需回复前,请勿继续执行。
- 必须采用发布密钥直接传入模式
- 将开发者提供的发布密钥直接传入。
<ClerkProvider publishableKey={key}> - 除非开发者明确要求或项目遵循快速开始模式,否则请勿引入环境变量间接传递()。
process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY
- 包安装规则必须遵守
- 如果未安装,使用
@clerk/expo进行安装。npx expo install @clerk/expo - 为所选策略安装匹配的对等依赖项(详见prebuilt.md/custom.md中的各流程依赖列表)。
- 在/
app.json中注册Expo配置插件:app.config.js。{ "plugins": ["@clerk/expo"] }
- 自定义流程必须调用环境接口
- 对于自定义流程:从发布密钥推导Frontend API URL,调用,并使用响应结果确定启用的因素/策略。
/v1/environment?_is_native=true - 构建内部启用因素清单;覆盖所有启用的因素,除非开发者明确缩小范围。
- 请勿跳过环境接口调用,请勿根据惯例假设策略覆盖范围。
- 必须遵守参考文件规则
- 选择流程后,仅遵循该流程的参考文件进行实现和验证。
- 自定义流程必须优先参考钩子源码
- 在决定流程转换之前,检查已安装的和
@clerk/expo钩子源码中的响应/错误处理逻辑。@clerk/react - 镜像钩子源码中的状态驱动转换,而非基于UI启发式或假设。
- 默认实现合并式登录或注册流程
- 默认实现一个合并的登录/注册流程;除非开发者明确要求分离,否则请勿拆分为单独的登录/注册流程。
- 禁止使用已废弃的钩子
- 切勿使用。始终使用
useOAuth()处理OAuth和企业SSO。useSSO()
- 平台/构建限制
- 原生组件和原生钩子(、
useSignInWithGoogle、useSignInWithApple、useNativeSession、useUserProfileModal)需要iOS/Android开发构建,而非Expo Go或Web。useLocalCredentials - 对于Web目标,使用导出的内容。
@clerk/expo/web - 在推荐仅支持原生的功能之前,务必说明平台可用性。
- 令牌缓存规则必须遵守
- 使用中的
@clerk/expo/token-cache实现会话持久化;请勿直接使用tokenCache存储令牌。expo-secure-store
Workflow
工作流程
- Detect Expo/React Native vs native iOS/Android vs web framework.
- If flow type is not explicitly provided, ask user for or
prebuilt.custom - If publishable key is not explicitly provided for a setup task, ask user for it.
- Wait for required answers before changing files.
- Load the matching flow reference file.
- Ensure is at the app root with the publishable key wired directly and
<ClerkProvider>fromtokenCache.@clerk/expo/token-cache - Ensure is installed and the Expo config plugin is registered. Install peer deps for selected strategies.
@clerk/expo - Inspect installed source for components/hooks relevant to the selected flow.
@clerk/expo - For custom flows: derive Frontend API URL from publishable key, call , and build an internal enabled-factor checklist.
/v1/environment?_is_native=true - Verify Expo quickstart prerequisites (config plugin, token cache, native development build) and apply any missing required setup.
- Implement using selected reference checklist.
- For custom flows: verify implemented strategy coverage against the environment-derived checklist; close any missing enabled factor unless explicitly scoped out.
- Verify using selected reference checklist plus shared gates.
- 检测项目类型是Expo/React Native、原生iOS/Android还是Web框架。
- 如果未明确提供流程类型,询问用户选择还是
prebuilt。custom - 如果设置任务未明确提供发布密钥,向用户索要。
- 在获得所需回复前,请勿修改文件。
- 加载对应的流程参考文件。
- 确保位于应用根节点,直接传入发布密钥,并使用
<ClerkProvider>中的@clerk/expo/token-cache。tokenCache - 确保已安装且Expo配置插件已注册。为所选策略安装对等依赖项。
@clerk/expo - 检查已安装的源码中与所选流程相关的组件/钩子。
@clerk/expo - 对于自定义流程:从发布密钥推导Frontend API URL,调用,并构建内部启用因素清单。
/v1/environment?_is_native=true - 验证Expo快速开始的先决条件(配置插件、令牌缓存、原生开发构建),并补充任何缺失的必要设置。
- 使用所选参考文件的清单进行实现。
- 对于自定义流程:验证已实现的策略覆盖范围是否符合环境接口返回的清单;除非明确排除,否则补充所有缺失的启用因素。
- 使用所选参考文件的清单以及通用限制进行验证。
Common Pitfalls
常见陷阱
| Level | Issue | Prevention |
|---|---|---|
| CRITICAL | Not asking for missing flow choice before implementation | Ask for |
| CRITICAL | Not asking for missing publishable key on setup tasks | Ask for key and wait before edits |
| CRITICAL | Wiring publishable key via env-var indirection by default | Pass key directly to |
| CRITICAL | Skipping | Call environment endpoint and build enabled-factor checklist before implementing |
| CRITICAL | Splitting sign-in / sign-up by default | Implement one combined sign-in-or-up flow unless developer explicitly requests separation |
| CRITICAL | Using | Always use |
| CRITICAL | Mixing native components with custom hook flows for the same auth step | Pick one flow per step; only blend with explicit developer approval |
| CRITICAL | Skipping native development build for native components/hooks | Require |
| HIGH | Using | Use |
| HIGH | Calling | |
| HIGH | Calling | Native components sync session automatically |
| HIGH | Hardcoding OAuth provider lists | Build provider lists from environment-enabled providers |
| HIGH | Recommending native-only hooks without web/Expo Go fallback | Note platform availability and provide |
| 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 |
| HIGH | Using | Use Verdaccio or pkg.pr.new |
| 级别 | 问题 | 预防措施 |
|---|---|---|
| 严重 | 实现前未询问缺失的流程选择 | 询问用户选择 |
| 严重 | 设置任务中未询问缺失的发布密钥 | 索要密钥,等待回复后再进行编辑 |
| 严重 | 默认通过环境变量间接传递发布密钥 | 直接将密钥传入 |
| 严重 | 自定义流程中跳过 | 实现前调用环境接口并构建启用因素清单 |
| 严重 | 默认拆分登录/注册流程 | 默认实现合并式登录/注册流程,除非开发者明确要求分离 |
| 严重 | 使用已废弃的 | 始终使用 |
| 严重 | 在同一身份验证步骤中混用原生组件和自定义钩子流程 | 每个步骤选择一种流程;仅在开发者明确批准时混合使用 |
| 严重 | 为原生组件/钩子跳过原生开发构建 | 要求使用 |
| 高 | 直接使用 | 使用 |
| 高 | 手动调用 | |
| 高 | 原生组件验证后调用 | 原生组件会自动同步会话 |
| 高 | 硬编码OAuth提供商列表 | 根据环境接口返回的启用提供商构建列表 |
| 高 | 推荐仅支持原生的钩子时未提供Web/Expo Go备选方案 | 说明平台可用性,并在必要时提供 |
| 高 | 将本技能用于原生iOS/Android或纯Web框架项目 | 检测项目类型并路由到clerk-swift/clerk-android/Web框架技能 |
| 高 | 使用 | 使用Verdaccio或pkg.pr.new |
See Also
另请参阅
- skill for top-level Clerk routing
clerk - skill (
clerk-expo-patterns) for Expo-specific recipes (SecureStore token cache, OAuth deep links, Expo Router protected routes, push notifications)skills/frameworks/clerk-expo-patterns/ - skill for native iOS implementation
clerk-swift - skill for native Android implementation
clerk-android - installed package source (
@clerk/expo)node_modules/@clerk/expo/ https://github.com/clerk/javascript/tree/main/packages/expohttps://github.com/clerk/clerk-expo-quickstart- (Expo SDK tab)
https://clerk.com/docs/getting-started/quickstart https://clerk.com/docs/reference/expo/overview
- 技能:用于顶层Clerk路由
clerk - 技能(
clerk-expo-patterns):用于Expo特定方案(SecureStore令牌缓存、OAuth深度链接、Expo Router受保护路由、推送通知)skills/frameworks/clerk-expo-patterns/ - 技能:用于原生iOS实现
clerk-swift - 技能:用于原生Android实现
clerk-android - 已安装的包源码(
@clerk/expo)node_modules/@clerk/expo/ https://github.com/clerk/javascript/tree/main/packages/expohttps://github.com/clerk/clerk-expo-quickstart- (Expo SDK标签)
https://clerk.com/docs/getting-started/quickstart https://clerk.com/docs/reference/expo/overview