clerk-expo

Clerk Expo（React Native）

Expo／React Native プロジェクトに Clerk を実装します。このスキルには、安定したインターフェース（プロバイダー、トークンキャッシュ、フロー）に関する検証済みのパターンが含まれています。変更されやすい要素（コンポーネントの props、フックのシグネチャ）については、インストール済みの @clerk/expo パッケージのソースを確認する必要があります。

有効化ルール

次のいずれかに該当する場合に有効化します。

• ユーザーが Expo または React Native アプリの認証を求めている、あるいはネイティブアプリで @clerk/expo、ClerkProvider、Expo Router の認証、Clerk フックについて言及している。
• プロジェクトが Expo／React Native である（app.json／app.config.js、package.json に expo がある、metro.config.js、@clerk/expo 依存関係）。

次の場合は別のスキルに切り替えます。

• ネイティブ iOS／Swift プロジェクト（.xcodeproj、Package.swift）→ clerk-swift
• ネイティブ Android／Kotlin プロジェクト（React Native を使用しない build.gradle）→ clerk-android
• Web 専用フレームワーク（Next.js、Remix、プレーンな React など）→ 該当するフレームワークスキル

意図マップ

ユーザーの依頼に合う項目を選び、記載されているリファレンスを読み込みます。タスクに必要なものだけを読み込んでください。

ユーザーの意図（例）	パス	リファレンス
「アプリに認証を追加して」／「Clerk でサインインを追加して」	ネイティブの事前構築コンポーネント（デフォルト）	references/setup.md + references/prebuilt-components.md
「認証を追加して」、ただし Expo Go／Web／カスタム UI が必須	カスタムフロー	references/setup.md + references/custom-flows.md
「電話番号／SMS 認証」「メール OTP」「パスワードレス」	カスタムフロー、phoneCode／emailCode	references/custom-flows.md
「Google／Apple／GitHub でサインイン」「ソーシャルログイン」「SSO」	ブラウザー SSO またはネイティブボタン	references/sso-and-native-auth.md
「MFA／2FA／TOTP」「パスワードを忘れた場合」「メールリンク」	カスタムフローの追加機能	references/custom-flows.md
「ルート／画面を保護して」「サインアウト時にリダイレクトして」	Expo Router ガード	references/protected-routes.md
「ユーザープロフィールを表示して」「組織を切り替えて」「プッシュ通知」「サインアウト」「バックエンドを呼び出して」	アプリのレシピ	references/recipes.md
「生体認証ログイン」「Face ID」「パスキー」	デバイス機能	references/recipes.md

デフォルトの方針

ユーザーが UI を指定せずに「認証を追加して」と言った場合：

1. ネイティブの事前構築コンポーネント（@clerk/expo/native の AuthView と UserButton）をデフォルトで使用します。認証を最速で動作させる方法で、UI は Clerk が保守しています。ベータ版であり、開発ビルドが必要であることを開発者に伝えてください。
2. 次のいずれかに該当する場合は、カスタムフローに切り替えます。切り替える理由も伝えてください。
   • プロジェクトを Expo Go で実行する必要がある（開発ビルドなし）。
   • アプリが Web を対象としている（ネイティブコンポーネントは Web ではレンダリングされません）。
   • 開発者がテーマ設定の範囲を超えて、独自の UI や特定のブランド体験を求めている。
3. 開発者が既存の認証 UI を使っている場合は、現在の実装を拡張します。求められていない限り、カスタムフローを取り除いて AuthView を挿入する（またはその逆を行う）ことは避けてください。

同じ認証ステップで事前構築コンポーネントとカスタムフローを混在させないでください（例：AuthView とカスタムのパスワードフォームを併用する）。開発者が明示的に求めた場合に限り、混在が認められます。

クイックワークフロー

1. プロジェクトの種類（Expo／RN）を確認し、意図マップ／デフォルトの方針に従って進め方を選びます。
2. references/setup.md に従います。インストール、環境変数キー、プロバイダー、トークンキャッシュ、設定プラグイン、ビルドの種類を確認します。
3. ダッシュボードの前提条件（以下の Gate 2 と Gate 3）を確認します。
4. 選択したリファレンスのみを使用して実装します。
5. コードを書くだけでなく、ビルドして検証します。
   • プロジェクトの型チェックを実行します（npx tsc --noEmit または同等のコマンド）。
   • ビルドして起動します。ネイティブ機能では npx expo run:ios／run:android、Expo Go フローでは npx expo start を使用します。ビルドに失敗した場合は修正して再ビルドを繰り返してください。このスキルと SDK の説明が食い違う場合、インストール済み SDK に対するビルドエラーを正とします。修正を約 5 回試しても失敗する場合は、試行を続けず、どのように進めるか開発者に確認してください。
   • 開発者と一緒に実際に一度サインインし、アプリを再起動してもセッションが保持されることを確認します（トークンキャッシュが機能していること）。

実行前の確認事項（省略しないでください）

1. 公開可能キー — .env ファイルから process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY を読み取ります。NEXT_PUBLIC_ を使わず、ハードコードもしないでください。キーがない場合は、開発者にキーを尋ねるか、npx clerk@latest init --framework expo を実行して（SDK をインストールし、環境変数ファイルを書き込みます）、ファイルを編集する前に回答を待ってください。
2. Native API ダッシュボードの切り替え — インスタンスで Clerk の Native API を有効にする必要があります。Clerk Dashboard → ネイティブアプリケーション（https://dashboard.clerk.com/~/native-applications）に移動します。セットアップ時に開発者へこの設定を確認するよう伝えてください。ネイティブ統合には必須です。
3. 認証要素の利用可否 — 特定の方式（SMS、メールコード、ソーシャルプロバイダー）を実装する前に、その方式がインスタンスで有効になっていることを確認してください。公開可能キーの中央セグメントを Base64 デコードして Frontend API URL を導出し、<frontendApiUrl>/v1/environment?_is_native=true を取得するか、ダッシュボード（ユーザーと認証）で確認するよう開発者に依頼してください。特に SMS はインスタンスの設定に依存します。無効な認証要素向けに書いたコードは、ビルド時ではなく実行時に失敗します。
4. 現在のカスタムフロー API のみを使用 — @clerk/expo（v3.4 以降）の useSignIn() / useSignUp() は { signIn, errors, fetchStatus } を返し、メソッドベースのフロー（signIn.password()、signIn.phoneCode.sendCode()、signIn.finalize()）を使用します。旧来のパターン、つまり useSignIn() / useSignUp() から isLoaded / setActive を分割代入する方法（現在のフックはこれらを返しません）や、signIn.create() に prepareFirstFactor() / attemptFirstFactor() と setActive({ session }) を連結する方法は生成しないでください。このパターンは @clerk/expo/legacy にあり、既存の旧来コードの保守にのみ使用します。新しい作業には使わないでください。対象範囲に関する注記：useAuth() / useUser() の isLoaded は現在の API であり、ガードに必要です。signIn.create() 自体は高度なケース向けに引き続き使用できますが、認証要素別のメソッドを優先してください。
5. useSSO() を使用し、useOAuth() は使用しない — useOAuth は非推奨です。戻り値の違いに注意してください。startSSOFlow() は引き続き { createdSessionId, setActive } を返し、setActive({ session: createdSessionId }) が必要です。SSO では finalize() を使用しません。
6. トークンキャッシュ — ClerkProvider では @clerk/expo/token-cache の tokenCache を使用してください。セッショントークンに expo-secure-store を直接使用せず、AsyncStorage も使用しないでください。
7. secureStore ではなく resourceCache を使用 — オフラインのリソースキャッシュを扱う場合、@clerk/expo/secure-store は非推奨です。代わりに @clerk/expo/resource-cache の resourceCache を使用してください。
8. ビルドタイプの条件 — ネイティブコンポーネント（@clerk/expo/native）とネイティブフック（useSignInWithGoogle、useSignInWithApple、useLocalCredentials）には開発ビルド（npx expo run:ios / run:android）が必要です。Expo Go では使用できず、Web にも存在しません。Web ターゲットでは @clerk/expo/web コンポーネントまたはカスタムフローを使用してください。ネイティブ専用機能を実装する前に、ビルド要件を伝えてください。
9. サインインまたはサインアップを組み合わせたフローをデフォルトにする — 開発者からサインイン画面とサインアップ画面を分けるよう依頼された場合を除き、両方を組み合わせたフローを 1 つ使用します。
10. ボット対策 — カスタムのサインアップ画面には <View nativeID="clerk-captcha" /> をレンダリングする必要があります。Clerk のボット対策はデフォルトで有効になっており、このマウントポイントが必要です。
11. 変更されやすい領域のソース確認 — ネイティブコンポーネントの props またはネイティブフックのオプションを使用する前に、インストール済みパッケージの node_modules/@clerk/expo/dist/native/*.d.ts と package.json の exports を確認してください。内容がこのスキルと異なる場合は、インストール済みバージョンを優先します。
12. 鮮度の確認 — このスキルは @clerk/expo 3.6.x に基づいて検証されています。インストール済みバージョン（node_modules/@clerk/expo/package.json）を確認してください。より新しいマイナーまたはメジャーバージョンの場合は、このスキルのコード例をそのまま信用せず、各コード例の隣に記載されたドキュメント URL（各リファレンスセクションに記載されています）またはインストール済みの .d.ts で再確認してください。3.4 より古い場合、メソッドベースのカスタムフロー API が存在しない可能性があります。旧来コードを書くのではなく、アップグレードを提案してください。

バージョンノート（v3.5–v3.6、2026年6月）

• v3.5.0 で React Native の最小バージョンが 0.75 に引き上げられました（iOS SDK は SPM podspec 経由でリンクされるようになりました）。ピア依存関係の範囲：expo >=53 <57
• ネイティブコンポーネントが成熟しました。iOS は Expo Modules に移行し、ネイティブ↔JS のセッション同期が自動かつ双方向になりました。ネイティブコンポーネントによる認証後に setActive() を呼び出さないでください。
• 設定プラグインで、ネイティブコンポーネントのスタイル設定用に theme JSON ファイルを指定できるようになりました（references/prebuilt-components.md を参照）。
• ネイティブ Google サインインは、次のメジャーバージョンで別パッケージ @clerk/expo-google-signin に移行する予定です（v3 では @clerk/expo/google のインポートも引き続き機能し、開発時の警告で移行が案内されます）。v3 では新しいパッケージを事前インストールしないでください。

よくある落とし穴

レベル	問題	防止策
CRITICAL	レガシーなカスタムフローのコードを生成する（signIn.create + prepareFirstFactor + setActive）	現行のメソッドベースの API を使用する（ゲート 4）
CRITICAL	useOAuth() を使用する	useSSO() を使用する（ゲート 5）
CRITICAL	要素が有効か確認せずに SMS／ソーシャル認証を実装する	まず環境／ダッシュボードを確認する（ゲート 3）
CRITICAL	Expo Go または Web を対象にネイティブコンポーネントを使用する	開発ビルドを必須にし、それ以外ではカスタムフローを提案する（ゲート 8）
CRITICAL	サインアップ画面に <View nativeID="clerk-captcha" /> がない	必ず含める（ゲート 10）
HIGH	NEXT_PUBLIC_ 環境変数プレフィックスを使用する、または環境変数を node_modules 内で読み込む	EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY を ClerkProvider に明示的に渡す
HIGH	再起動後にセッションが失われる	プロバイダーで @clerk/expo/token-cache の tokenCache を使用する
HIGH	AuthView／UserButton による認証後に setActive() を呼び出す	ネイティブコンポーネントがセッションを自動で同期する
HIGH	AuthView と useSignInWithGoogle／useSignInWithApple を組み合わせる	AuthView が有効なソーシャルプロバイダーを自ら表示する
HIGH	WebBrowser.maybeCompleteAuthSession() を手動で呼び出す	ClerkProvider が処理する
HIGH	求められていないのにサインイン／サインアップを分ける	デフォルトでは統合フローを使用する（ゲート 9）
MEDIUM	ガードで isSignedIn の前に isLoaded を確認しない	常に最初に isLoaded で判定する
MEDIUM	ローカルの @clerk/expo 開発に yalc／pnpm link を使用する	Verdaccio または pkg.pr.new を使用する

関連項目

• clerk — トップレベルのルーター
• clerk-swift／clerk-android — ネイティブモバイル SDK
• clerk-orgs、clerk-billing、clerk-webhooks — 機能スキル（フックは Expo でも同様に動作します）
• インストール済みパッケージのソース：node_modules/@clerk/expo/
• https://clerk.com/docs/getting-started/quickstart（Expo SDK タブ）
• https://clerk.com/docs/reference/expo/overview
• https://github.com/clerk/clerk-expo-quickstart — 公式サンプルアプリ 3 種：JS のみ（Expo Go）、JS + ネイティブサインインボタン、ネイティブコンポーネント