convex-nextjs

Convex + Next.js

このスキルを使う場面

• 新規または既存の Next.js アプリで Convex をセットアップする。
• スキーマ、インデックス、関数、UI フック、認証、デプロイまで、機能を一気通貫で追加する。
• よくある統合の失敗（プロバイダーの不足、生成コードの不足、クライアント／サーバー境界の誤り、環境変数の不足）をデバッグする。
• リアルタイム機能または共同作業機能を備えた Next.js アプリに Convex が適しているかを評価する。

このスキルを使わない場面

• Convex に依存しない、通常の Next.js UI 作業の場合。
• バックエンドが Convex ではないことが確定しており、ユーザーも移行を検討していない場合。
• Next.js／Convex の実装作業を伴わない、一般的なデータベース理論の問題の場合。

基本方針

• 開発には npx convex dev を使用します。
• リアクティブフックはクライアントコンポーネントに配置します。
• .filter(...) よりもインデックスを使ったクエリを優先します。
• 上限のないリストは、デフォルトでページネーションするものとして扱います。
• 外部 I/O はアクションに配置し、Node API または未対応パッケージが必要な場合に限り "use node" を追加します。
• 公開関数では入力検証を必須とし、特別な理由がない限り戻り値の検証も追加します。
• ユーザーデータには、明示的な認証チェックと所有権チェックを追加します。
• 同じ認証／テナントチェックが繰り返される場合は、ヘルパー関数またはカスタムラッパーを優先します。

リポジトリを確認して答える最初の質問

1. 新規アプリ、既存の Next.js アプリ、それとも移行ですか？
2. App Router、Pages Router、またはその両方ですか？
3. この機能に必要なのはリアクティブ性、SSR、サーバーアクション、それともそのすべてですか？
4. データセットには上限がありますか、それともページネーションが必要ですか？
5. 認証はすでに導入されていますか？導入済みの場合、クライアントのみで必要ですか、それともサーバーでも必要ですか？
6. Convex コンポーネントを使うことで、この機能の再利用性や分離性が高まりますか？

ワークフロー 1 — 適切な開始方法を選ぶ

A. 新規プロジェクト

次を優先します：

npm create convex@latest

ユーザーが維持したい Next.js アプリの構成をすでに持っている場合は、代わりに方法 B を使います。

B. 既存の Next.js アプリ

Convex をインストールし、開発時の同期を開始します：

npm install convex
npx convex dev

想定される結果：

• convex/ が存在するか、convex.json で指定されたカスタム関数ディレクトリが存在する
• 生成ファイルが _generated/ 以下に作成される
• 開発用デプロイまたはローカルデプロイが接続される
• フロントエンドで NEXT_PUBLIC_CONVEX_URL を利用できる

references/01-setup-and-decision-tree.md を参照してください。

ワークフロー 2 — 画面の形ではなく、クエリパターンに基づいてデータをモデル化する

UI を書く前に、以下を定義します：

• テーブル
• 所有権を示すフィールド
• 主な読み取り処理に必要なインデックス
• リストに上限があるか、ページネーションするか
• 大きなドキュメントではなく、Convex File Storage にファイルを保存すべきか

ルール：

• 深くネストされた大きなデータより、フラットなリレーショナル形式のドキュメントを優先します。
• リレーションには v.id("table") を使用します。
• 必要と分かっている、繰り返し使うフィルター／ソートのパターンごとにインデックスを追加します。
• クエリが上限のないテーブルをスキャンする場合は、インデックスを設計し直すか、ページネーションします。

references/02-schema-and-indexes.md を参照してください。

ワークフロー 3 — 適切な Convex 関数の種類を選ぶ

Query

読み取り専用の処理に使います。小さく、インデックスを使い、予測可能なものにします。

Mutation

書き込みと、トランザクション内での読み書き処理に使います。

Action

外部 API、長時間実行される処理、またはトランザクション対象外のオーケストレーションに使います。

• fetch で十分な場合は、デフォルトの Convex ランタイムを使います。
• Node 専用 API または未対応パッケージが必要な場合に限り "use node" を追加します。
• "use node" を含むファイルには、アクションのみを記述します。

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

ワークフロー 4 — バリデーション、認証、所有権を早い段階で適用する

公開関数では、以下を行います。

• args を定義します
• 通常は returns も定義します
• 関数が保護されている場合は、ctx.auth.getUserIdentity() を呼び出します
• 認証だけでなく、所有権やチームへの所属も確認します
• チェックの重複が広がり始めたら、繰り返し行う確認をヘルパーやカスタムラッパーに移します

認証やテナントの確認が多くの関数で繰り返される場合は、以下を検討します。

• convex/lib/auth.ts のヘルパー
• query、mutation、action 向けの薄いラッパーやカスタム関数
• テナントやリソースの確認に使う共有ポリシーヘルパー

references/05-auth-and-access-control.md を参照してください。

ワークフロー 5 — Next.js の境界を尊重する

• useQuery、useMutation、useAction、usePaginatedQuery、usePreloadedQuery はクライアントコンポーネントで使用します。
• 初回表示を速くするリアクティブ優先のページでは、サーバーコンポーネントで preloadQuery を使い、クライアントコンポーネントで usePreloadedQuery を使います。
• サーバー専用の読み取りには、fetchQuery を使います。
• Server Actions または Route Handlers には、fetchMutation または fetchAction を使います。

サーバーコンポーネントから React フックを呼び出さないでください。

references/04-nextjs-client-and-server-boundaries.md を参照してください。

ワークフロー 6 — 大きなリストはページネーションの問題として扱う

以下に該当する場合は、デフォルトでページネーションを使用します。

• ユーザーが「すべて」、「フィード」、「アクティビティ」、「履歴」、「メッセージ」、「通知」、「検索結果」、「無限スクロール」と指定している
• テーブルが自然な上限なく増え続ける可能性がある
• ユーザー向けのリストで .collect() を使おうとしている

パターン：

• バックエンドのクエリでは .paginate(paginationOpts) を使います
• React クライアントでは usePaginatedQuery を使います

references/06-pagination-performance-and-realtime.md を参照してください。

ワークフロー 7 — 機能を分離するならコンポーネントを検討する

以下に該当する機能では、Convex コンポーネントを使う価値があります。

• 独自のスキーマ、関数、内部ジョブを持つ
• 複数のアプリで再利用する必要がある
• 使わない場合、密結合したコードでルートの convex/ フォルダーが煩雑になる

機能が小さく、1 つのアプリに固有の場合は、通常のアプリコードを使います。

references/07-components-migrations-and-reuse.md を参照してください。

ワークフロー 8 — 適切な開発モードを選ぶ

• 自分のマシンやローカルのコーディングエージェントでは、通常の npx convex dev が適しています。
• ログインできないリモートエージェントやバックグラウンドエージェントでは、Agent Mode を使います。
• 分離されたローカルのみの開発では、ローカルデプロイを使います。

references/08-local-dev-agent-mode-and-cloud-agents.md を参照してください。

ワークフロー 9 — 終了前に検証する

実行します：

python {baseDir}/scripts/validate_project.py --root .

便利なフラグ：

python {baseDir}/scripts/validate_project.py --root . --strict
python {baseDir}/scripts/validate_project.py --root . --json

バリデーターは、このスキルで検出を想定している一般的な問題をチェックします。

• Convex のインストールまたは生成済みコードがない
• プロバイダーまたは環境変数の設定がない
• クライアント以外のコンポーネントでフックを使用している
• テーブルへのアクセスが暗黙的である
• クエリで .collect() または .filter() を使用している
• Convex 関数にバリデーターがない
• リスクのある "use node" ファイルの混在
• 公開関数を対象としたスケジューラー呼び出し
• TypeScript の厳密性が不足している、または Convex ESLint プラグインがない

ワークフロー 10 — クリーンにデプロイする

通常の開発では、引き続き以下を使います。

npx convex dev

本番環境または CI では：

npx convex deploy

Vercel ビルドでは、一般的に以下のパターンを使います。

npx convex deploy --cmd "npm run build"

references/09-deploy-ci-and-vercel.md を参照してください。

強力な最終実装に通常含まれるもの

• 更新済みの convex/schema.ts
• 新規または更新されたインデックス
• args と、通常は returns を持つ公開関数
• 必要に応じた認証または所有権の確認
• 生成された api を通じて接続された UI
• 実際に必要な箇所だけの "use client"
• 上限のない collect ではなく、ページネーションを使ったリスト
• 必要な環境変数に関するメモ
• 変更を検証するためにユーザーが実行すべきコマンド

コード変更時に推奨する回答の形式

1. 追加または編集するファイルを示します。
2. アーキテクチャ上の選択を1文で説明します。
3. コードの変更を適用します。
4. バリデーターを実行するか、実行する具体的なチェックを説明します。
5. 追加で必要になる環境変数、認証の設定、デプロイ手順、移行に関する懸念事項を挙げます。

リファレンスマップ

• セットアップとパスの選択：references/01-setup-and-decision-tree.md
• スキーマとインデックスの設計：references/02-schema-and-indexes.md
• 関数、バリデーション、Node アクション、スケジューラーの安全性：references/03-functions-and-safety.md
• Next.js のクライアント／サーバー境界と SSR：references/04-nextjs-client-and-server-boundaries.md
• 認証とアクセス制御：references/05-auth-and-access-control.md
• ページネーション、パフォーマンス、リアルタイム機能：references/06-pagination-performance-and-realtime.md
• コンポーネント、移行、再利用：references/07-components-migrations-and-reuse.md
• ローカル開発、Agent Mode、ローカルデプロイ：references/08-local-dev-agent-mode-and-cloud-agents.md
• デプロイと CI：references/09-deploy-ci-and-vercel.md
• トラブルシューティングとスモークテスト：references/10-troubleshooting-and-smoke-tests.md