clerk-expo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clerk Expo (React Native)

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.
本技能通过检查已安装的
@clerk/expo
包源码并镜像当前钩子和组件的行为,在Expo/React Native项目中实现Clerk身份验证。

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.
当满足以下任一条件时激活本技能:
  • 用户明确询问Expo、React Native、
    @clerk/expo
    ClerkProvider
    或相关Clerk组件/钩子的实现方法。
  • 项目看起来是Expo/React Native类型(例如存在
    app.json
    app.config.js
    metro.config.js
    package.json
    中有
    expo
    @clerk/expo
    依赖)。
当满足以下任一条件时请勿激活本技能:
  • 项目是原生iOS/Swift类型(存在
    .xcodeproj
    .xcworkspace
    Package.swift
    、Swift目标文件)。
  • 项目是原生Android/Kotlin类型(存在带Android插件的
    build.gradle(.kts)
    AndroidManifest.xml
    ,无React Native相关内容)。
  • 项目是纯Web框架(Next.js、Remix等)且不包含Expo/React Native。
如果检测到原生iOS/Android或Web框架的特征,请将请求路由到对应的技能,而非本技能。

Relationship to
clerk-expo-patterns

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.
本技能涵盖流程选择和端到端身份验证设置(预构建 vs 自定义)。位于
skills/frameworks/clerk-expo-patterns/
clerk-expo-patterns
技能则涵盖Expo特定的方案(SecureStore令牌缓存、OAuth深度链接配置、Expo Router受保护路由、带用户上下文的推送通知)。当两个技能都适用时,使用本技能进行流程决策和整体设置,并从
clerk-expo-patterns
加载特定方案的模式。

What Do You Need?

所需资源

TaskReference
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

快速开始

StepAction
1Confirm project type is Expo/React Native (not native iOS/Android or a web-only framework)
2Determine flow type (
prebuilt
or
custom
) and load the matching reference file
3Ensure a real Clerk publishable key exists (or ask developer) and wire it directly to
<ClerkProvider publishableKey={...}>
4Ensure
@clerk/expo
is installed; if missing, install latest with
npx expo install @clerk/expo
5Inspect installed
@clerk/expo
source (
node_modules/@clerk/expo/dist/
or
src/
) to understand component/hook behavior for the selected flow
6For custom flows: derive Frontend API URL from publishable key, then call
<frontendApiUrl>/v1/environment?_is_native=true
and build an internal enabled-factor checklist
7Follow the Expo quickstart (
https://clerk.com/docs/getting-started/quickstart
, Expo SDK tab) for required setup (config plugin, token cache, native build)
8Implement flow by following only the selected reference checklist
步骤操作
1确认项目类型为Expo/React Native(而非原生iOS/Android或纯Web框架)
2确定流程类型(
prebuilt
custom
)并加载对应的参考文件
3确保存在有效的Clerk发布密钥(或向开发者索要),并直接将其传入
<ClerkProvider publishableKey={...}>
4确保已安装
@clerk/expo
;若未安装,使用
npx expo install @clerk/expo
安装最新版本
5检查已安装的
@clerk/expo
源码(
node_modules/@clerk/expo/dist/
src/
),了解所选流程的组件/钩子行为
6对于自定义流程:从发布密钥推导Frontend API URL,调用
<frontendApiUrl>/v1/environment?_is_native=true
并构建内部启用因素清单
7遵循Expo快速开始指南(
https://clerk.com/docs/getting-started/quickstart
,Expo SDK标签)完成必要设置(配置插件、令牌缓存、原生构建)
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 reference
text
用户询问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:
    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.
在进行任何实现编辑之前,智能代理必须同时具备:
  • 流程选择:
    prebuilt
    custom
  • 有效的Clerk发布密钥(当设置/配置是任务的一部分时)
如果用户请求/上下文中缺少任一值:
  • 向用户询问缺失的值
  • 暂停并等待回复
  • 暂不编辑文件或安装依赖
仅当用户在本次对话中已明确提供对应值时,才可跳过询问步骤。

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 CaseSource 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 checklistOfficial Expo quickstart (
https://clerk.com/docs/getting-started/quickstart
, Expo SDK tab)
请勿在本技能中硬编码实现示例。在实现前,请检查项目中已安装的
@clerk/expo
版本的源码。
使用场景已安装包中的事实来源
包导出和子路径(
@clerk/expo/google
/apple
/native
/token-cache
/local-credentials
/resource-cache
/web
node_modules/@clerk/expo/package.json
exports
字段以及
dist/
中的编译输出
钩子签名和返回类型
node_modules/@clerk/expo/dist/*.d.ts
以及从
node_modules/@clerk/react/dist/*.d.ts
重新导出的类型
原生组件属性和事件
node_modules/@clerk/expo/dist/native/*
(搜索
AuthView
InlineAuthView
UserButton
UserProfileView
登录/注册状态转换
node_modules/@clerk/react/dist/
钩子源码(搜索
useSignIn
useSignUp
status
SSO和OAuth行为
node_modules/@clerk/expo/dist/
(搜索
useSSO
startSSOFlow
session_exists
transferable
原生Google/Apple登录路径
node_modules/@clerk/expo/google
/apple
模块
令牌持久化
node_modules/@clerk/expo/token-cache
(基于
expo-secure-store
实现)
原生SDK与JS之间的会话同步
node_modules/@clerk/expo/dist/native/
(搜索
NativeSessionSync
useNativeAuthEvents
Expo配置插件行为
node_modules/@clerk/expo/app.plugin.js
(搜索
withClerkGoogleSignIn
withClerkAndroidPackaging
必要的Expo设置清单官方Expo快速开始指南(
https://clerk.com/docs/getting-started/quickstart
,Expo SDK标签)

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.
  1. 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.
  1. 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.
  1. 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"] }
    .
  1. 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.
  1. Reference-file discipline is mandatory
  • Once flow is selected, follow only that flow reference file for implementation and verification.
  1. Hook-source-first discipline for custom flows
  • Inspect installed
    @clerk/expo
    and
    @clerk/react
    hook source for response/error handling before deciding flow transitions.
  • Mirror status-driven transitions from hook source rather than from UI heuristics or assumptions.
  1. 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.
  1. Deprecated hook prohibition
  • Never use
    useOAuth()
    . Always use
    useSSO()
    for OAuth and Enterprise SSO.
  1. Platform / build gating
  • Native components and native hooks (
    useSignInWithGoogle
    ,
    useSignInWithApple
    ,
    useNativeSession
    ,
    useUserProfileModal
    ,
    useLocalCredentials
    ) require an iOS/Android development build, not Expo Go and not web.
  • For web targets, use
    @clerk/expo/web
    exports.
  • Always note platform availability before recommending native-only features.
  1. Token cache discipline
  • Use
    tokenCache
    from
    @clerk/expo/token-cache
    for persistent sessions; do not use
    expo-secure-store
    directly for token storage.
  1. 完成先决条件前不得进行实现编辑
  • 在确认流程类型且(当涉及设置时)获得有效的发布密钥之前,请勿编辑项目文件。
  1. 缺失流程或密钥必须触发询问
  • 如果缺少流程选择,明确询问:使用预构建视图还是自定义流程。
  • 如果设置任务中缺少发布密钥/密钥为占位符/无效,明确索要有效的密钥。
  • 在获得所需回复前,请勿继续执行。
  1. 必须采用发布密钥直接传入模式
  • 将开发者提供的发布密钥直接传入
    <ClerkProvider publishableKey={key}>
  • 除非开发者明确要求或项目遵循快速开始模式,否则请勿引入环境变量间接传递(
    process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY
    )。
  1. 包安装规则必须遵守
  • 如果未安装
    @clerk/expo
    ,使用
    npx expo install @clerk/expo
    进行安装。
  • 为所选策略安装匹配的对等依赖项(详见prebuilt.md/custom.md中的各流程依赖列表)。
  • app.json
    /
    app.config.js
    中注册Expo配置插件:
    { "plugins": ["@clerk/expo"] }
  1. 自定义流程必须调用环境接口
  • 对于自定义流程:从发布密钥推导Frontend API URL,调用
    /v1/environment?_is_native=true
    ,并使用响应结果确定启用的因素/策略。
  • 构建内部启用因素清单;覆盖所有启用的因素,除非开发者明确缩小范围。
  • 请勿跳过环境接口调用,请勿根据惯例假设策略覆盖范围。
  1. 必须遵守参考文件规则
  • 选择流程后,仅遵循该流程的参考文件进行实现和验证。
  1. 自定义流程必须优先参考钩子源码
  • 在决定流程转换之前,检查已安装的
    @clerk/expo
    @clerk/react
    钩子源码中的响应/错误处理逻辑。
  • 镜像钩子源码中的状态驱动转换,而非基于UI启发式或假设。
  1. 默认实现合并式登录或注册流程
  • 默认实现一个合并的登录/注册流程;除非开发者明确要求分离,否则请勿拆分为单独的登录/注册流程。
  1. 禁止使用已废弃的钩子
  • 切勿使用
    useOAuth()
    。始终使用
    useSSO()
    处理OAuth和企业SSO。
  1. 平台/构建限制
  • 原生组件和原生钩子(
    useSignInWithGoogle
    useSignInWithApple
    useNativeSession
    useUserProfileModal
    useLocalCredentials
    )需要iOS/Android开发构建,而非Expo Go或Web。
  • 对于Web目标,使用
    @clerk/expo/web
    导出的内容。
  • 在推荐仅支持原生的功能之前,务必说明平台可用性。
  1. 令牌缓存规则必须遵守
  • 使用
    @clerk/expo/token-cache
    中的
    tokenCache
    实现会话持久化;请勿直接使用
    expo-secure-store
    存储令牌。

Workflow

工作流程

  1. Detect Expo/React Native vs native iOS/Android vs web framework.
  2. If flow type is not explicitly provided, ask user for
    prebuilt
    or
    custom
    .
  3. If publishable key is not explicitly provided for a setup task, ask user for it.
  4. Wait for required answers before changing files.
  5. Load the matching flow reference file.
  6. Ensure
    <ClerkProvider>
    is at the app root with the publishable key wired directly and
    tokenCache
    from
    @clerk/expo/token-cache
    .
  7. Ensure
    @clerk/expo
    is installed and the Expo config plugin is registered. Install peer deps for selected strategies.
  8. Inspect installed
    @clerk/expo
    source for components/hooks relevant to the selected flow.
  9. For custom flows: derive Frontend API URL from publishable key, call
    /v1/environment?_is_native=true
    , and build an internal enabled-factor checklist.
  10. Verify Expo quickstart prerequisites (config plugin, token cache, native development build) and apply any missing required setup.
  11. Implement using selected reference checklist.
  12. For custom flows: verify implemented strategy coverage against the environment-derived checklist; close any missing enabled factor unless explicitly scoped out.
  13. Verify using selected reference checklist plus shared gates.
  1. 检测项目类型是Expo/React Native、原生iOS/Android还是Web框架。
  2. 如果未明确提供流程类型,询问用户选择
    prebuilt
    还是
    custom
  3. 如果设置任务未明确提供发布密钥,向用户索要。
  4. 在获得所需回复前,请勿修改文件。
  5. 加载对应的流程参考文件。
  6. 确保
    <ClerkProvider>
    位于应用根节点,直接传入发布密钥,并使用
    @clerk/expo/token-cache
    中的
    tokenCache
  7. 确保
    @clerk/expo
    已安装且Expo配置插件已注册。为所选策略安装对等依赖项。
  8. 检查已安装的
    @clerk/expo
    源码中与所选流程相关的组件/钩子。
  9. 对于自定义流程:从发布密钥推导Frontend API URL,调用
    /v1/environment?_is_native=true
    ,并构建内部启用因素清单。
  10. 验证Expo快速开始的先决条件(配置插件、令牌缓存、原生开发构建),并补充任何缺失的必要设置。
  11. 使用所选参考文件的清单进行实现。
  12. 对于自定义流程:验证已实现的策略覆盖范围是否符合环境接口返回的清单;除非明确排除,否则补充所有缺失的启用因素。
  13. 使用所选参考文件的清单以及通用限制进行验证。

Common Pitfalls

常见陷阱

LevelIssuePrevention
CRITICALNot asking for missing flow choice before implementationAsk for
prebuilt
vs
custom
and wait before edits
CRITICALNot asking for missing publishable key on setup tasksAsk for key and wait before edits
CRITICALWiring publishable key via env-var indirection by defaultPass key directly to
<ClerkProvider>
unless developer requests otherwise
CRITICALSkipping
/v1/environment?_is_native=true
for custom flows
Call environment endpoint and build enabled-factor checklist before implementing
CRITICALSplitting sign-in / sign-up by defaultImplement one combined sign-in-or-up flow unless developer explicitly requests separation
CRITICALUsing
useOAuth()
(deprecated)
Always use
useSSO()
CRITICALMixing native components with custom hook flows for the same auth stepPick one flow per step; only blend with explicit developer approval
CRITICALSkipping native development build for native components/hooksRequire
expo run:ios
/
expo run:android
; do not target Expo Go for native features
HIGHUsing
expo-secure-store
directly for token caching
Use
tokenCache
from
@clerk/expo/token-cache
HIGHCalling
WebBrowser.maybeCompleteAuthSession()
manually
ClerkProvider
handles it; do not duplicate
HIGHCalling
setActive()
after native component auth
Native components sync session automatically
HIGHHardcoding OAuth provider listsBuild provider lists from environment-enabled providers
HIGHRecommending native-only hooks without web/Expo Go fallbackNote platform availability and provide
useSSO()
fallback where needed
HIGHUsing this skill for native iOS/Android or web-only framework projectsDetect and route away to clerk-swift / clerk-android / web-framework skills
HIGHUsing
yalc
or
pnpm link
for local @clerk/expo development
Use Verdaccio or pkg.pr.new
级别问题预防措施
严重实现前未询问缺失的流程选择询问用户选择
prebuilt
还是
custom
,等待回复后再进行编辑
严重设置任务中未询问缺失的发布密钥索要密钥,等待回复后再进行编辑
严重默认通过环境变量间接传递发布密钥直接将密钥传入
<ClerkProvider>
,除非开发者明确要求其他方式
严重自定义流程中跳过
/v1/environment?_is_native=true
调用
实现前调用环境接口并构建启用因素清单
严重默认拆分登录/注册流程默认实现合并式登录/注册流程,除非开发者明确要求分离
严重使用已废弃的
useOAuth()
始终使用
useSSO()
严重在同一身份验证步骤中混用原生组件和自定义钩子流程每个步骤选择一种流程;仅在开发者明确批准时混合使用
严重为原生组件/钩子跳过原生开发构建要求使用
expo run:ios
/
expo run:android
;请勿针对Expo Go使用原生功能
直接使用
expo-secure-store
进行令牌缓存
使用
@clerk/expo/token-cache
中的
tokenCache
手动调用
WebBrowser.maybeCompleteAuthSession()
ClerkProvider
会处理此操作;请勿重复实现
原生组件验证后调用
setActive()
原生组件会自动同步会话
硬编码OAuth提供商列表根据环境接口返回的启用提供商构建列表
推荐仅支持原生的钩子时未提供Web/Expo Go备选方案说明平台可用性,并在必要时提供
useSSO()
作为备选
将本技能用于原生iOS/Android或纯Web框架项目检测项目类型并路由到clerk-swift/clerk-android/Web框架技能
使用
yalc
pnpm link
进行本地@clerk/expo开发
使用Verdaccio或pkg.pr.new

See Also

另请参阅

  • clerk
    skill for top-level Clerk routing
  • clerk-expo-patterns
    skill (
    skills/frameworks/clerk-expo-patterns/
    ) for Expo-specific recipes (SecureStore token cache, OAuth deep links, Expo Router protected routes, push notifications)
  • clerk-swift
    skill for native iOS implementation
  • clerk-android
    skill for native Android implementation
  • installed
    @clerk/expo
    package source (
    node_modules/@clerk/expo/
    )
  • https://github.com/clerk/javascript/tree/main/packages/expo
  • https://github.com/clerk/clerk-expo-quickstart
  • https://clerk.com/docs/getting-started/quickstart
    (Expo SDK tab)
  • https://clerk.com/docs/reference/expo/overview
  • clerk
    技能:用于顶层Clerk路由
  • clerk-expo-patterns
    技能(
    skills/frameworks/clerk-expo-patterns/
    ):用于Expo特定方案(SecureStore令牌缓存、OAuth深度链接、Expo Router受保护路由、推送通知)
  • clerk-swift
    技能:用于原生iOS实现
  • clerk-android
    技能:用于原生Android实现
  • 已安装的
    @clerk/expo
    包源码(
    node_modules/@clerk/expo/
  • https://github.com/clerk/javascript/tree/main/packages/expo
  • https://github.com/clerk/clerk-expo-quickstart
  • https://clerk.com/docs/getting-started/quickstart
    (Expo SDK标签)
  • https://clerk.com/docs/reference/expo/overview