integrating-clerk-expo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clerk authentication in Expo (React Native)

Expo（React Native）中的Clerk认证

Key constraints (read first)

关键约束条件（请先阅读）

Expo native apps do not support Clerk email links. Prefer email verification codes (
```
email_code
```
) or other strategies.
Clerk prebuilt UI components are not supported on Expo native. Use custom flows (your own screens) plus the control components:
```
<ClerkLoaded>
```
,
```
<ClerkLoading>
```
,
```
<SignedIn>
```
,
```
<SignedOut>
```
,
```
<Protect>
```
.
Default session tokens are in-memory; for native apps you almost always want a secure token cache (Expo SecureStore).

Expo原生应用不支持Clerk邮箱链接。优先选择邮箱验证码（
```
email_code
```
）或其他方案。
Clerk预构建UI组件在Expo原生环境中不支持。请使用自定义流程（自有页面）搭配控制组件：
```
<ClerkLoaded>
```
、
```
<ClerkLoading>
```
、
```
<SignedIn>
```
、
```
<SignedOut>
```
、
```
<Protect>
```
。
默认会话令牌存储在内存中；对于原生应用，几乎总是需要安全令牌缓存（Expo SecureStore）。

What this skill does

本方案的功能

When implementing Clerk in an Expo app, follow these workflows to:

Install and configure
```
@clerk/clerk-expo
```
and environment keys
Wrap the app in
```
<ClerkProvider>
```
with a secure
```
tokenCache
```
Build custom sign-in/sign-up screens (email + password, email codes)
Protect routes/screens in Expo Router or React Navigation
Add OAuth / Enterprise SSO flows via
```
useSSO()
```
(and fix redirect/deeplink pitfalls)
Add native Sign in with Apple (iOS, native build) via
```
useSignInWithApple()
```
Add optional biometric re-auth via
```
useLocalCredentials()
```
Optionally enable experimental offline bootstrapping via
```
__experimental_resourceCache
```
Prepare for production deployment (domain + allowlisted redirect URLs)

在Expo应用中集成Clerk时，请遵循以下流程：

安装并配置
```
@clerk/clerk-expo
```
及环境密钥
使用安全的
```
tokenCache
```
将应用包裹在
```
<ClerkProvider>
```
中
构建自定义登录/注册页面（邮箱+密码、邮箱验证码）
在Expo Router或React Navigation中保护路由/页面
通过
```
useSSO()
```
添加OAuth/企业SSO流程（并修复重定向/深度链接问题）
通过
```
useSignInWithApple()
```
添加原生Apple登录（iOS原生构建）
通过
```
useLocalCredentials()
```
添加可选的生物识别重新认证功能
可选通过
```
__experimental_resourceCache
```
启用实验性离线引导
为生产部署做准备（域名+重定向URL白名单）

Fast checklist (default: Expo Router)

快速检查清单（默认：Expo Router）

Copy/paste and tick off:

In Clerk Dashboard, enable Native API for the application.
Install:
```
@clerk/clerk-expo
```

Add

.env

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=...

Wrap the root with
```
<ClerkProvider tokenCache={tokenCache}>
```
Install SecureStore and use Clerk’s
```
tokenCache
```
helper

Create

(auth)

route group with

sign-in.tsx

sign-up.tsx

, and an

(auth)/_layout.tsx

redirect guard

Add a sign-out button using
```
useClerk().signOut()
```
Protect signed-in content using
```
<SignedIn>
```
/
```
<SignedOut>
```
/
```
<Protect>
```
or
```
useAuth()
```
+ redirects

If using OAuth/SSO: implement

useSSO()

expo-auth-session

redirect URL +

WebBrowser.maybeCompleteAuthSession()

If iOS Apple sign-in is required: native build +
```
useSignInWithApple()
```

If you need resilience offline:

__experimental_resourceCache={resourceCache}

and handle

network_error

Production: acquire a domain and allowlist mobile SSO redirect URLs

If you need full code examples, open:

```
references/QUICKSTART.md
```
```
references/CUSTOM_FLOWS.md
```
```
references/SSO_OAUTH.md
```
```
references/HOOKS_AND_COMPONENTS.md
```

复制粘贴并勾选完成：

在Clerk控制台中，为应用启用Native API。
安装：
```
@clerk/clerk-expo
```

添加

.env

：

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=...

使用
```
<ClerkProvider tokenCache={tokenCache}>
```
包裹根组件
安装SecureStore并使用Clerk的
```
tokenCache
```
工具

创建

(auth)

路由组，包含

sign-in.tsx

、

sign-up.tsx

和

(auth)/_layout.tsx

重定向守卫

使用
```
useClerk().signOut()
```
添加登出按钮
使用
```
<SignedIn>
```
/
```
<SignedOut>
```
/
```
<Protect>
```
或
```
useAuth()
```
+重定向来保护登录后内容

如果使用OAuth/SSO：实现

useSSO()

expo-auth-session

重定向URL +

WebBrowser.maybeCompleteAuthSession()

如果需要iOS Apple登录：原生构建 +
```
useSignInWithApple()
```

如果需要离线 resilience：

__experimental_resourceCache={resourceCache}

并处理

network_error

生产环境：获取域名并将移动端SSO重定向URL加入白名单

如需完整代码示例，请查看：

```
references/QUICKSTART.md
```
```
references/CUSTOM_FLOWS.md
```
```
references/SSO_OAUTH.md
```
```
references/HOOKS_AND_COMPONENTS.md
```

Decide the routing setup

确定路由配置

If the project uses Expo Router

如果项目使用Expo Router

Signals:

```
expo-router
```
dependency
an
```
app/
```
directory with route files like
```
app/_layout.tsx
```

➡️ Follow: Expo Router workflow (below).

特征：

依赖
```
expo-router
```
存在
```
app/
```
目录，包含
```
app/_layout.tsx
```
等路由文件

➡️ 遵循：Expo Router流程（下文）。

If the project uses React Navigation directly (no Expo Router)

如果项目直接使用React Navigation（无Expo Router）

Signals:

```
App.tsx
```
with
```
NavigationContainer
```
and stacks
no
```
app/
```
directory

➡️ Follow: React Navigation workflow (below).

特征：

```
App.tsx
```
包含
```
NavigationContainer
```
和导航栈
无
```
app/
```
目录

➡️ 遵循：React Navigation流程（下文）。

Workflow A — Expo Router (recommended default)

流程A — Expo Router（推荐默认方案）

1) Install + env key

1) 安装 + 环境密钥

Install
```
@clerk/clerk-expo
```
Set
```
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY
```
in
```
.env
```

安装
```
@clerk/clerk-expo
```
在
```
.env
```
中设置
```
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY
```

2) Root layout: ClerkProvider + secure token cache

2) 根布局：ClerkProvider + 安全令牌缓存

app/_layout.tsx

(or the project’s root layout), wrap your app:

tsx

import { ClerkProvider } from '@clerk/clerk-expo'
import { tokenCache } from '@clerk/clerk-expo/token-cache'
import { Slot } from 'expo-router'

export default function RootLayout() {
  return (
    <ClerkProvider tokenCache={tokenCache}>
      <Slot />
    </ClerkProvider>
  )
}

Notes:

Ensure
```
expo-secure-store
```
is installed (required by the
```
tokenCache
```
helper).
Keep only the publishable key in the client.

在

app/_layout.tsx

（或项目的根布局）中，包裹应用：

tsx

import { ClerkProvider } from '@clerk/clerk-expo'
import { tokenCache } from '@clerk/clerk-expo/token-cache'
import { Slot } from 'expo-router'

export default function RootLayout() {
  return (
    <ClerkProvider tokenCache={tokenCache}>
      <Slot />
    </ClerkProvider>
  )
}

注意：

确保已安装
```
expo-secure-store
```
（
```
tokenCache
```
工具依赖此包）。
客户端仅保留可公开访问的密钥。

3) Auth route group + redirect guard

3) 认证路由组 + 重定向守卫

Create

app/(auth)/_layout.tsx

that redirects signed-in users away from auth screens:

tsx

import { Redirect, Stack } from 'expo-router'
import { useAuth } from '@clerk/clerk-expo'

export default function AuthLayout() {
  const { isSignedIn } = useAuth()
  if (isSignedIn) return <Redirect href="/" />
  return <Stack />
}

创建

app/(auth)/_layout.tsx

，将已登录用户从重定向出认证页面：

tsx

import { Redirect, Stack } from 'expo-router'
import { useAuth } from '@clerk/clerk-expo'

export default function AuthLayout() {
  const { isSignedIn } = useAuth()
  if (isSignedIn) return <Redirect href="/" />
  return <Stack />
}

4) Build custom sign-in / sign-up screens

4) 构建自定义登录/注册页面

Use Clerk hooks (

useSignIn

useSignUp

) and prefer

email_code

verification.

See:

```
references/CUSTOM_FLOWS.md
```

使用Clerk钩子（

useSignIn

、

useSignUp

），优先选择

email_code

验证方式。

查看：

```
references/CUSTOM_FLOWS.md
```

5) Protect signed-in routes

5) 保护登录后路由

Options (pick one, don’t mix randomly):

Declarative: Wrap signed-in areas with
```
<SignedIn>
```
and
```
<SignedOut>
```
.
Gate a subtree: Use
```
<Protect>
```
around content that requires auth.
Imperative: In a layout, check
```
useAuth()
```
and
```
<Redirect>
```
to
```
/sign-in
```
.

See:

```
references/ROUTING.md
```

可选方案（选其一，不要随意混合）：

声明式：用
```
<SignedIn>
```
和
```
<SignedOut>
```
包裹登录后区域。
子树守卫：用
```
<Protect>
```
包裹需要认证的内容。
命令式：在布局中检查
```
useAuth()
```
并通过
```
<Redirect>
```
跳转到
```
/sign-in
```
。

查看：

```
references/ROUTING.md
```

Workflow B — React Navigation (no Expo Router)

流程B — React Navigation（无Expo Router）

1) Wrap the root

1) 包裹根组件

Wrap your

NavigationContainer

(or your app root) with

<ClerkProvider tokenCache={tokenCache}>

用

<ClerkProvider tokenCache={tokenCache}>

包裹

NavigationContainer

（或应用根组件）。

2) Split navigation by auth state

2) 根据认证状态拆分导航

While
```
!isLoaded
```
: render a splash/loading screen
When
```
isSignedIn
```
: render your “app” stack
Else: render your “auth” stack

See:

```
references/ROUTING.md
```

当
```
!isLoaded
```
时：渲染启动/加载页面
当
```
isSignedIn
```
时：渲染“应用”导航栈
否则：渲染“认证”导航栈

查看：

```
references/ROUTING.md
```

OAuth / Enterprise SSO in Expo (useSSO)

Expo中的OAuth/企业SSO（useSSO）

Use

useSSO()

for OAuth + enterprise SSO. In native, you must provide a valid redirect URL (often via

AuthSession.makeRedirectUri(...)

) and ensure your redirect URLs are allowlisted for production.

See:

```
references/SSO_OAUTH.md
```
```
references/DEPLOYMENT.md
```

使用

useSSO()

实现OAuth+企业SSO。在原生环境中，必须提供有效的重定向URL（通常通过

AuthSession.makeRedirectUri(...)

生成），并确保生产环境中重定向URL已加入白名单。

查看：

```
references/SSO_OAUTH.md
```
```
references/DEPLOYMENT.md
```

Sign in with Apple (iOS native build)

Apple登录（iOS原生构建）

useSignInWithApple()

is iOS-only and requires a native build (won’t work in Expo Go). Always handle

ERR_REQUEST_CANCELED

See:

```
references/APPLE_SIGNIN.md
```

useSignInWithApple()

仅支持iOS，且需要原生构建（在Expo Go中无法使用）。请务必处理

ERR_REQUEST_CANCELED

错误。

查看：

```
references/APPLE_SIGNIN.md
```

Biometrics (store local credentials)

生物识别（存储本地凭证）

useLocalCredentials()

can store password credentials on-device and allow biometric sign-in later (Face ID / fingerprint). Only works for password-based sign-in attempts.

See:

```
references/BIOMETRICS.md
```

useLocalCredentials()

可在设备上存储密码凭证，后续允许通过生物识别登录（面容ID/指纹）。仅适用于基于密码的登录场景。

查看：

```
references/BIOMETRICS.md
```

Passkeys

密钥凭证（Passkeys）

Clerk supports passkeys (WebAuthn). In Expo apps, you’ll integrate passkeys through custom flows; follow Clerk’s passkeys reference for the latest supported strategies and platform constraints.

See:

```
references/PASSKEYS.md
```

Clerk支持密钥凭证（WebAuthn）。在Expo应用中，需通过自定义流程集成密钥凭证；请遵循Clerk的密钥凭证参考文档，了解最新支持的方案和平台约束。

查看：

```
references/PASSKEYS.md
```

Offline support (experimental)

离线支持（实验性）

You can enable experimental offline bootstrapping via

__experimental_resourceCache

. Treat as experimental; add good error handling for

network_error

See:

```
references/OFFLINE_SUPPORT.md
```

可通过

__experimental_resourceCache

启用实验性离线引导。请将其视为实验功能；需为

network_error

添加完善的错误处理。

查看：

```
references/OFFLINE_SUPPORT.md
```

Validation loop (recommended)

验证流程（推荐）

Run the setup verifier:

bash

python scripts/verify_expo_clerk_setup.py .

Start Expo with a clean cache:

bash

npx expo start -c

Test flows:

fresh install → sign up → verify code → app screen
app restart → user still signed in (token cache working)
sign out → user returns to auth stack (token cleared)

运行设置验证脚本：

bash

python scripts/verify_expo_clerk_setup.py .

清除缓存后启动Expo：

bash

npx expo start -c

测试流程：

全新安装 → 注册 → 验证验证码 → 进入应用页面
重启应用 → 用户仍保持登录状态（令牌缓存生效）
登出 → 用户返回认证栈（令牌已清除）

THE EXACT PROMPT — Implement Clerk in an Expo app

精确提示 — 在Expo应用中实现Clerk

Use this when delegating to another coding agent:

You are implementing Clerk authentication in a React Native Expo app.

1) Detect whether this app uses Expo Router (app/ directory) or React Navigation.
2) Install and configure @clerk/clerk-expo with EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY.
3) Wrap the root with <ClerkProvider tokenCache={tokenCache}> and ensure expo-secure-store is installed.
4) Implement custom sign-in and sign-up screens (email + password, with email verification code strategy 'email_code').
5) Protect signed-in routes appropriately for the chosen router.
6) If OAuth/SSO is requested, implement useSSO() with expo-auth-session redirectUrl and WebBrowser.maybeCompleteAuthSession().
7) Add sign-out.
8) Provide a short test plan and run scripts/verify_expo_clerk_setup.py.

Be precise and keep changes minimal. Do not use email link flows on native.

当委派给其他编码代理时使用：

你需要在React Native Expo应用中实现Clerk认证。

1) 检测应用使用的是Expo Router（app/目录）还是React Navigation。
2) 安装并配置@clerk/clerk-expo，设置EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY。
3) 使用<ClerkProvider tokenCache={tokenCache}>包裹根组件，并确保已安装expo-secure-store。
4) 实现自定义登录和注册页面（邮箱+密码，采用邮箱验证码策略'email_code'）。
5) 根据所选路由方案，合理保护登录后路由。
6) 如果需要OAuth/SSO，实现useSSO()，搭配expo-auth-session的redirectUrl和WebBrowser.maybeCompleteAuthSession()。
7) 添加登出功能。
8) 提供简短测试计划，并运行scripts/verify_expo_clerk_setup.py。

请保持精准，尽量减少变更。原生环境请勿使用邮箱链接流程。

Quick search (when reading bundled references)

快速搜索（查看捆绑参考文档时）

bash

grep -Rni "useSSO" references/
grep -Rni "tokenCache" references/
grep -Rni "enterprise_sso" references/
grep -Rni "__experimental_resourceCache" references/

bash

grep -Rni "useSSO" references/
grep -Rni "tokenCache" references/
grep -Rni "enterprise_sso" references/
grep -Rni "__experimental_resourceCache" references/