integrating-convex-expo

Convex と Expo（React Native）の統合

このスキルは、Web 専用のパターンや一般的な React Native のアドバイスに逸脱せずに、Expo アプリ向けの Convex バックエンドを追加、修復、拡張、または強化するために使用します。

このスキルを使用する場面

• 既存の Expo または Expo Router アプリに Convex を追加する。
• 環境設定、プロバイダーの接続、または生成された API のインポートに関する問題を修正する。
• スキーマ、インデックス、バックエンド関数、フロントエンドのフック、バリデーションを含む、エンドツーエンドの機能一式を構築する。
• Expo + Convex 向けの認証方式を選択して実装する。
• Expo の URI から Convex ストレージにファイルをアップロードする。
• ページネーション、インデックス、マイグレーション、または再利用可能なコンポーネントに対応できるようリファクタリングする。
• プレビューまたは本番リリースの前にプロジェクトを強化する。

このスキルを使用しない場面

• Convex を使用しない、Expo の UI、アニメーション、ナビゲーション、またはスタイリングのみの作業。
• フロントエンドが Expo または React Native ではない Convex プロジェクト。
• Expo 固有の環境設定やクライアントの接続を必要としない、一般的なバックエンドアーキテクチャの議論。

成功基準

良好な結果では、プロジェクトが次の状態になります。

1. 適切なスコープで設定された Convex クライアントとプロバイダーがそれぞれ 1 つだけある。
2. ローカル開発環境と EAS で EXPO_PUBLIC_CONVEX_URL が正しく処理される。
3. バリデーター、認証、アクション、クエリのパフォーマンスについて、Convex のベストプラクティスに従ったバックエンド関数がある。
4. 生成された api 参照を使用し、読み込み中、空、エラーの状態が明確なフロントエンドフックがある。
5. scripts/validate_project.py による検証が完了している。
6. ページネーション、インデックス、認証ラッパー、マイグレーション、リンティングに対応できる、明確な将来への拡張方針がある。

必須事項

• 統合の開発や修復中は npx convex dev を実行し続けてください。
• デプロイ URL は process.env.EXPO_PUBLIC_CONVEX_URL から読み込んでください。
• プレビューと本番のビルドに備えて、その値を EAS 環境にも設定してください。
• アプリごとに ConvexReactClient を 1 つだけ作成し、レンダリング処理の外に配置してください。
• プロバイダーは、真のルートである app/_layout.tsx、src/app/_layout.tsx、または App.tsx に配置してください。
• Expo と React Native では、unsavedChangesWarning: false を設定してください。
• 文字列ベースの型付けされていない名前ではなく、convex/_generated/api から生成された参照をインポートしてください。
• クライアントから呼び出せる Convex 関数は、すべて信頼できないエントリーポイントとして扱ってください。
• 公開関数には args バリデーターを追加し、returns バリデーターも使用することを推奨します。
• 公開ラッパーは薄く保ち、繰り返し使うロジックはヘルパー、内部関数、またはカスタムラッパーに移してください。
• クエリのロジック内では Date.now() や new Date() を使用しないでください。
• クエリやミューテーション内で、Node 専用 API やサードパーティ SDK を使用しないでください。
• 外部 API 呼び出し、負荷の高い計算、または Node 専用ライブラリは、action または internalAction ファイルに配置してください。ファイルが "use node" で始まる場合は、アクション専用にしてください。
• 大規模なテーブルで .filter() や上限のない .collect() を避け、インデックスとページネーションを優先してください。
• すべての Promise を await してください。
• TypeScript の strict モードと、公式 Convex ESLint プラグインを優先してください。

最初のトリアージ

変更を加える前に、プロジェクトを調査して作業内容を分類してください。

1. アプリのエントリーポイントを特定する

次を確認してください。

• Expo Router の場合は、app/_layout.tsx または src/app/_layout.tsx。
• 従来型のエントリーポイントの場合は、App.tsx または App.jsx。

2. Convex の状態を監査する

次を確認してください。

• package.json の依存関係：convex、expo、認証ライブラリ、ESLint ツール。
• convex/ と convex/_generated/。
• .env.local、.env、.env.development、.env.production。
• クラウドビルドが関係する場合は eas.json。
• 既存のプロバイダーの使用状況：ConvexProvider、ConvexProviderWithClerk、またはカスタム認証ラッパー。
• convex/schema.ts にある既存のスキーマとインデックス。
• バリデーター、認証チェック、またはページネーションが不足している既存の公開関数。

3. バリデーターを実行する

プロジェクトのルートから実行してください。

python scripts/validate_project.py --root <project-root>

機械可読な出力には --json を、より厳格な判定を行う場合は --fail-on-warning を使用してください。

4. ワークフローを選択する

• ベースラインのセットアップ／修復：Convex のセットアップ、環境変数、プロバイダー、または生成済み API が不足している場合。
• 機能を一通り実装する：バックエンドのデータと UI をまとめて追加する場合。
• 認証：サインインとバックエンドの認可を追加または修復する場合。
• ファイルアップロード：メディアやドキュメントをデバイスの URI から Convex ストレージに移す場合。
• スケール／堅牢化：インデックス、ページネーション、コンポーネント、リンティング、本番環境向けチェックリスト。
• 移行：既存のテーブルを再構成する場合、または別のバックエンドから段階的に移行する場合。

ワークフロー A — ベースラインの連携をセットアップまたは修復する

ステップ 1：クライアントパッケージをインストールまたは確認する

npx expo install convex

ステップ 2：Convex プロジェクトを作成または再接続する

npx convex dev

これにより、次の処理が行われます。

• Convex プロジェクトを作成または接続する
• convex/ が存在しない場合は作成する
• convex/_generated/ を生成する
• EXPO_PUBLIC_CONVEX_URL を .env.local に書き込む
• コマンドの実行中は同期を継続する

ステップ 3：ルートプロバイダーが存在することを確認する

Expo Router の場合：

import { ConvexProvider, ConvexReactClient } from "convex/react";
import { Stack } from "expo-router";

const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
  unsavedChangesWarning: false,
});

export default function RootLayout() {
  return (
    <ConvexProvider client={convex}>
      <Stack />
    </ConvexProvider>
  );
}

従来の App.tsx の場合は、同じ方法で最上位のナビゲーションツリーをラップします。

ステップ 4：生成されたインポートを確認する

次を使用します。

import { api } from "../convex/_generated/api";

または、プロジェクトの構成に応じた正しい相対パスを使用します。関数名を手書きしないでください。

ステップ 5：開発環境とビルド環境を確認する

references/eas-env.md を読み、同じデプロイ URL ポリシーが EAS にも反映されていることを確認します。

ステップ 6：検証とスモークテストを行う

• Expo アプリを起動します。
• useQuery(...) の値が undefined から実データに変わることを確認します。
• python scripts/validate_project.py --root <project-root> を実行します。
• 必要に応じて、python scripts/scaffold_tasks_example.py --root <project-root> で標準的なサンプルを生成します。

ワークフロー B — 機能をエンドツーエンドで実装する

以下の順序で各機能を実装します。

1. まずデータアクセスパターンをモデル化する

コードに手を加える前に、次の点を確認します。

• データは公開、ユーザー単位、組織単位、または管理者専用のどれですか？
• リストは小さいままですか、それともページネーションが必要ですか？
• 検索キーとなるフィールドはどれですか？そのためにインデックスが必要ですか？
• 外部 API、AI SDK、Stripe、または Node API が必要なステップはありますか？

2. スキーマを設計する

データモデルが固まりつつある場合は、関数レイヤーに取り組む前に convex/schema.ts を追加または拡張します。

references/schema-and-indexes.md を参照して、次の内容を確認します。

• フラットなリレーショナルモデリング
• 外部キーのインデックス作成
• 実際のクエリ形状に沿った複合インデックス
• 配列サイズの上限に関する指針
• ページネーションのしきい値

3. バックエンド関数を実装する

詳しいパターンについては references/functions.md を参照してください。

基本ルール：

• 決定的な読み取りには query を使用します。
• 書き込みには mutation を使用します。
• 外部 API、サードパーティ SDK、または Node 専用コードには action または internalAction を使用します。
• クライアントから呼び出されるべきでないロジックには internalQuery または internalMutation を使用します。

4. バックエンドでアクセスを制御する

機能が公開でない場合は、次のいずれかを実施します。

• 各関数で ctx.auth.getUserIdentity() を明示的に確認する
• convex-helpers を使って再利用可能なカスタムラッパーを作成する

references/auth.md と references/components-and-helpers.md を参照してください。

5. フロントエンドを接続する

references/frontend-patterns.md を参照してください。

次の項目には必ず対応します。

• 読み込み中：useQuery(...) === undefined
• 空の状態
• 必要に応じたミューテーションの保留状態
• 回復可能なエラー
• 件数に上限のないリストのページネーション

6. 機能全体を検証する

完了前に、次の作業を行います。

• プロジェクトのルートを指定してバリデーターを実行する
• プロジェクトに設定されている場合は、リンティングと型チェックを実行する
• デバイスまたはシミュレーターで機能を確認する
• リリース前にインデックスを更新または追加する

ワークフロー C — 認証と認可

認証方式を 1 つ選び、スタック全体で一貫性を保ちます。

オプション 1：Clerk

アプリですでに Clerk を使用している場合や、洗練された認証プロダクトを導入したい場合に適しています。

オプション 2：Convex Auth

Convex ネイティブの認証スタックを希望し、ベータ版ライブラリの採用に問題がない場合に適しています。

オプション 3：既存の JWT または OIDC プロバイダー

製品がすでに Auth0、WorkOS、会社の IdP、または別の OIDC フローに依存している場合に適しています。

プロバイダーに関係なく適用するルール

• バックエンドでの認可は必須です。クライアント側の制御は UX のためにのみ使用してください。
• Convex にユーザーを永続化する場合は、tokenIdentifier などの安定した識別子でインデックスを作成してください。
• 保護された関数では、毎回、所有権、組織への所属、またはロールを確認してください。
• 認証の定型コードを繰り返すのではなく、ヘルパー関数やカスタムラッパーを優先してください。
• 特権を要する内部専用の処理には、内部関数を使用してください。

判断マトリクスと実装パターンについては、references/auth.md をお読みください。

ワークフロー D — Expo からのファイルアップロード

生ファイルをミューテーション経由で送ろうとせず、Convex のアップロード URL を使用してください。

推奨フロー：

1. 公開または保護されたミューテーションが ctx.storage.generateUploadUrl() を返す、
2. クライアントが fetch(uri) でローカルの file:// URI を読み込み、Blob に変換する、
3. クライアントがアップロード URL に Blob を POST する、
4. 2 つ目のミューテーションが、返された storageId とアプリ固有のメタデータを保存する、
5. 必要に応じて、その後にスケジュール実行またはアクションベースの後処理を行う。

references/file-uploads.md をお読みください。

ワークフロー E — 拡張と強化

基本的な仕組みが動作したら、品質基準を引き上げましょう。

パフォーマンス

• 可能であれば、.filter() による走査をインデックス付きクエリに置き換えてください。
• 上限のない .collect() を take、first、またはページネーション付きクエリに置き換えてください。
• 増加し続けるフィード、通知、無限スクロール画面には usePaginatedQuery を使用してください。
• 境界が明確な場合は、繰り返し利用できる機能領域を Convex コンポーネントに移してください。

安全性

• バリデーターを一貫して追加してください。
• 特権を要するロジックは内部関数の背後に置いてください。
• 想定されるエラーには ConvexError または明確な戻り値の形式を使用してください。
• 所有権や所属を確認せずに、クライアントから渡された ID を決して信頼しないでください。

保守性

• @convex-dev/eslint-plugin を有効にしてください。
• TypeScript の strict モードを使用してください。
• ラッパーは薄く保ち、共通ロジックは通常の TypeScript ヘルパーに移してください。
• "use node" のアクションファイルは、通常のランタイムファイルと分離してください。

references/production-checklist.md をお読みください。

ワークフロー F — マイグレーション

稼働中のスキーマを変更する場合は、加算的な移行を優先してください。

デフォルトのマイグレーション戦略：

1. 新しいフィールドまたはテーブルを後方互換性のある方法で追加する、
2. データ形状を変更する場合は、読み取りまたは書き込みを二重化する、
3. 冪等なバッチで既存のドキュメントをバックフィルする、
4. 読み取り側と書き込み側を切り替える、
5. その後、古いデータ形状を削除する。

バックフィルには内部関数またはスケジュール済みジョブを使用し、マイグレーションが再起動に安全であることを確認してください。

references/migrations.md をお読みください。

トラブルシューティングの手順

アプリが動作しない場合は、次の順に確認してください。

1. npx convex dev は実行中で、TypeScript エラーはありませんか？
2. .env.local に EXPO_PUBLIC_CONVEX_URL が含まれていますか？
3. 環境ファイルを変更した後、Metro を再起動しましたか？
4. ConvexReactClient は 1 つだけですか？
5. プロバイダーは実際のルートにマウントされていますか？
6. convex/_generated/api は存在し、インポート先も正しく指定されていますか？
7. 公開関数に args または returns のバリデーターが不足していませんか？
8. クエリで Date.now()、.filter()、または上限のない .collect() を使用していませんか？
9. "use node" ファイル内で、クエリやミューテーションを誤って混在させていませんか？
10. クライアントプロバイダーとバックエンド設定の間で、認証の設定が一致していますか？

references/troubleshooting.md をご覧ください。

利用可能なスクリプト

• scripts/validate_project.py

  • --root で指定した場所をルートとするプロジェクト、またはリポジトリにコピーされている場合は現在の作業ツリーを検証します。
  • Expo と Convex の依存関係を検証します。
  • 環境変数ファイル、プロバイダーの配線、生成コード、バリデーターの有無、"use node" の誤用、一般的なクエリのアンチパターンをチェックします。
  • --json、--root、--fail-on-warning に対応しています。

• scripts/scaffold_tasks_example.py

  • デフォルトではドライランを実行します。
  • sampleData.jsonl、convex/schema.ts、convex/tasks.ts、および任意の Expo 画面ファイルを生成できます。
  • --write、--overwrite、--ui-file、--json に対応しています。

参考資料

現在のタスクに該当するファイルのみ読み込んでください。

• references/eas-env.md — ローカル環境、EAS 環境、デプロイ URL の処理。
• references/tasks-example.md — このスタックの標準的な最小構成例。
• references/schema-and-indexes.md — スキーマ設計、インデックス、クエリ形状の対応付け、ページネーションの開始条件。
• references/functions.md — クエリ、ミューテーション、アクション、内部関数、バリデーター、ランタイムの境界。
• references/frontend-patterns.md — プロバイダーの配置、フックの使用方法、読み込み状態とエラー状態、ページネーション付きリスト。
• references/auth.md — Clerk、Convex Auth、JWT または OIDC、ユーザーのマッピング、サーバーサイドの認可。
• references/file-uploads.md — アップロード URL、Expo URI の処理、メタデータの保存、後処理。
• references/components-and-helpers.md — Convex コンポーネントと convex-helpers のパターン。
• references/migrations.md — 加算的なロールアウト、バックフィル、二重読み取りと書き込み、バッチ処理によるマイグレーション。
• references/production-checklist.md — リリース前の強化チェックリスト。
• references/troubleshooting.md — よくある問題と具体的な修正方法。
• references/evaluation.md — 同梱されているトリガー評価ファイルと出力評価ファイルの使用方法。
• references/sources.md — この改訂版で使用した上流のドキュメントと資料。