integrating-clerk-expo

Expo（React Native）での Clerk 認証

主な制約（最初にお読みください）

• Expo のネイティブアプリでは Clerk のメールリンクをサポートしていません。メール認証コード（email_code）などの方法を推奨します。
• Clerk の事前構築済み UI コンポーネントは Expo のネイティブアプリではサポートされていません。独自の画面を使ったカスタムフローと、次の制御コンポーネントを使用してください： <ClerkLoaded>、<ClerkLoading>、<SignedIn>、<SignedOut>、<Protect>。
• デフォルトではセッショントークンはメモリ内に保存されます。ネイティブアプリではほとんどの場合、セキュアなトークンキャッシュ（Expo SecureStore）が必要です。

このスキルの内容

Expo アプリに Clerk を実装する際は、次のワークフローに従ってください：

• @clerk/clerk-expo と環境変数キーをインストールして設定する
• セキュアな tokenCache を指定して <ClerkProvider> でアプリをラップする
• カスタムのサインイン／サインアップ画面（メールアドレス＋パスワード、メール認証コード）を作成する
• Expo Router または React Navigation でルート／画面を保護する
• useSSO() を使って OAuth／Enterprise SSO フローを追加する（リダイレクトやディープリンクの問題も解決する）
• useSignInWithApple() を使ってネイティブの Sign in with Apple（iOS、ネイティブビルド）を追加する
• useLocalCredentials() を使った任意の生体認証による再認証を追加する
• __experimental_resourceCache を使った実験的なオフライン起動機能を任意で有効にする
• 本番環境へのデプロイに備える（ドメインと許可リストに登録したリダイレクト URL）

クイックチェックリスト（デフォルト：Expo Router）

コピーして貼り付け、完了した項目にチェックを入れてください：

• Clerk Dashboard で、アプリケーションの Native API を有効にする。
• インストールする：@clerk/clerk-expo
• .env に追加する：EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=...
• <ClerkProvider tokenCache={tokenCache}> でルートをラップする
• SecureStore をインストールし、Clerk の tokenCache ヘルパーを使用する
• sign-in.tsx、sign-up.tsx、リダイレクトガードを含む (auth)/_layout.tsx を備えた (auth) ルートグループを作成する
• useClerk().signOut() を使ってサインアウトボタンを追加する
• <SignedIn> ／ <SignedOut> ／ <Protect> または useAuth() ＋ リダイレクトを使って、サインイン済みコンテンツを保護する
• OAuth／SSO を使用する場合：useSSO() ＋ expo-auth-session のリダイレクト URL ＋ WebBrowser.maybeCompleteAuthSession() を実装する
• iOS の Apple サインインが必要な場合：ネイティブビルド ＋ useSignInWithApple()
• オフライン時の耐障害性が必要な場合：__experimental_resourceCache={resourceCache} を設定し、network_error を処理する
• 本番環境：ドメインを取得し、モバイル SSO のリダイレクト URL を許可リストに登録する

コード例全体が必要な場合は、次を開いてください：

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

---

ルーティング設定を選択する

プロジェクトで Expo Router を使用している場合

判断の目安：

• expo-router 依存関係がある
• app/_layout.tsx のようなルートファイルを含む app/ ディレクトリがある

➡️ 次の Expo Router ワークフローに従ってください。

プロジェクトで React Navigation を直接使用している場合（Expo Router なし）

判断の目安：

• NavigationContainer とスタックを含む App.tsx がある
• app/ ディレクトリがない

➡️ 次の React Navigation ワークフローに従ってください。

---

ワークフロー A — Expo Router（デフォルトとして推奨）

1）インストールと環境変数キー

• @clerk/clerk-expo をインストールする
• .env に EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY を設定する

2）ルートレイアウト：ClerkProvider ＋ セキュアなトークンキャッシュ

app/_layout.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）認証用ルートグループとリダイレクトガード

サインイン済みユーザーを認証画面からリダイレクトする app/(auth)/_layout.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）カスタムのサインイン／サインアップ画面を作成する

Clerk フック（useSignIn、useSignUp）を使い、email_code による認証を推奨します。

参照先：

• references/CUSTOM_FLOWS.md

5) サインイン済みのルートを保護する

以下のオプションから1つ選び、無計画に組み合わせないでください。

• 宣言的：サインイン済みの領域を <SignedIn> と <SignedOut> で囲みます。
• サブツリーを保護：認証が必要なコンテンツを <Protect> で囲みます。
• 命令的：レイアウトで useAuth() を確認し、<Redirect> で /sign-in にリダイレクトします。

参照：

• references/ROUTING.md

---

ワークフロー B — React Navigation（Expo Router なし）

1) ルートをラップする

NavigationContainer（またはアプリのルート）を <ClerkProvider tokenCache={tokenCache}> でラップします。

2) 認証状態に応じてナビゲーションを分ける

• !isLoaded の間：スプラッシュ画面／読み込み画面を表示します
• isSignedIn の場合：「app」スタックを表示します
• それ以外の場合：「auth」スタックを表示します

参照：

• references/ROUTING.md

---

Expo での OAuth／エンタープライズ SSO（useSSO）

OAuth とエンタープライズ SSO には useSSO() を使用します。ネイティブ環境では、有効なリダイレクト URL（多くの場合、AuthSession.makeRedirectUri(...) を使用）を指定し、本番環境用のリダイレクト URL が許可リストに登録されていることを確認する必要があります。

参照：

• references/SSO_OAUTH.md
• references/DEPLOYMENT.md

---

Apple でサインイン（iOS ネイティブビルド）

useSignInWithApple() は iOS 専用で、ネイティブビルドが必要です（Expo Go では動作しません）。 必ず ERR_REQUEST_CANCELED を処理してください。

参照：

• references/APPLE_SIGNIN.md

---

生体認証（ローカル認証情報の保存）

useLocalCredentials() を使うと、パスワード認証情報をデバイス上に保存し、後で生体認証（Face ID／指紋）によるサインインを可能にできます。パスワードベースのサインイン試行でのみ機能します。

参照：

• references/BIOMETRICS.md

パスキー

Clerk はパスキー（WebAuthn）をサポートしています。Expo アプリでは、カスタムフローを通じてパスキーを統合します。最新の対応戦略とプラットフォームの制約については、Clerk のパスキーに関するリファレンスに従ってください。

参照：

• references/PASSKEYS.md

---

オフラインサポート（実験的）

__experimental_resourceCache を使って、実験的なオフライン起動を有効にできます。実験的機能として扱い、network_error に対する適切なエラー処理を追加してください。

参照：

• references/OFFLINE_SUPPORT.md

---

検証手順（推奨）

1. セットアップ検証ツールを実行します。

python scripts/verify_expo_clerk_setup.py .

2. キャッシュをクリアして Expo を起動します。

npx expo start -c

3. フローをテストします。

• 新規インストール → サインアップ → コードを検証 → アプリ画面
• アプリを再起動 → ユーザーが引き続きサインイン済みであること（トークンキャッシュが機能している）
• サインアウト → ユーザーが認証スタックに戻ること（トークンがクリアされる）

---

正確なプロンプト — Expo アプリに Clerk を実装する

別のコーディングエージェントに委任するときに、これを使用します。

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.

---

クイック検索（同梱のリファレンスを読む場合）

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