convex-quickstart

クイックスタート：実行中の最小限の Convex テンプレート

アイデアをもとに、匿名の開発用デプロイメントで最小限の Next.js + Convex テンプレートをローカルで立ち上げます。最小限にするため、ローカルの開発サーバーを使用し、公開手順や事前構築済みの認証はありません。

ワークフロー

1. {idea, template} を指定してレシピ quickstart-recipe@^2 を実行します（パックが取得してキャッシュします。固定されたオフライン用フォールバックもあります）。プロジェクトを作成し、依存関係をインストールして、バックエンド（匿名）と Web 開発サーバーを起動します。
2. 開発用 URL が表示されたら、ユーザーに開きます。
3. テンプレートを超える機能を構築する前に、簡潔な計画を提示して、必ず確認を取ります。

ルール

• レシピがすでに成功を報告している場合は、再実行しないでください。
• convex/ 配下のコードはすべて convex-expert 機能に委任してください。
• Postgres／Redis／Express は追加せず、Convex のプリミティブを使用してください。
• ホスティング／公開や、あらかじめ用意された認証機能は追加せず、ユーザーから求められない限りテンプレートは最小限に保ってください。
• 劣化時のルール — スキャフォールドを実行できない場合（非対話型セッション、ネットワークなし、サンドボックス化された一時ディレクトリ、またはユーザーがアプリではなくコードだけを求めている場合）は、レシピをスキップし、標準的な Convex プロジェクトを直接作成してください。バックエンドコードはすべて convex/ 配下（schema.ts、関数）に置いてください。プロジェクトのルートには絶対に置かないでください。Convex 関数は convex/ ディレクトリからのみ実行されます。明示的に求められない限り、スキャフォールド／ドキュメントファイル（START_HERE.md、ARCHITECTURE.md、MANIFEST.txt、README の長文など）は一切作成しないでください。「バックエンドを作って」は、形式的な手順ではなくコードを意味します。
• データアクセスとインポート — convex/*.ts を書く前に、増加し得るテーブルに対して上限のない .collect() を使用しないでください。.withIndex(...) と .paginate(...)／.take(n) を使用してください。SQL の WHERE 句に相当する処理には、.filter() ではなくインデックスを使用してください。.withIndex(...) のコールバックで使用できるのは eq／gt／gte／lt／lte だけで、.range(...) メソッドはありません。インポート：query／mutation／action／internalQuery／internalMutation／internalAction は ./_generated/server から、api／internal は ./_generated/api からインポートしてください。アプリケーションコードから convex/server をインポートしてはいけません。固定の文字列／列挙型メンバーには、単なる文字列ではなく v.literal("exact value") を使用してください。"use node" はアクション専用モジュールの先頭にのみ記述し、query または mutation もエクスポートするファイルには記述しないでください。"use node" がないファイルでは、Node の組み込みモジュール（crypto／fs／path／http／child_process／os。node: プレフィックスの有無は問いません）をインポートしてはいけません。http.ts のルートハンドラーも対象です。可能な場合は crypto を import せず、代わりに Web Crypto（crypto.subtle）を使用してください。
• 予約名 — クエリ／ミューテーション／アクションのエクスポート名として、export const <jsReservedWord> = ...（例：delete、new、class、function、return）を使わないでください。esbuild の解析に失敗します。_migrations: defineTable(...) のように、名前が _ で始まるテーブル名やインデックス名も使用しないでください。_ は予約されており、プッシュ時に TableNameReserved／IndexNameReserved エラーが発生します。
• HTTP ルート — httpRouter は Express 形式の :param セグメントをサポートしません（path: "/users/:id" はそのリテラル文字列にのみ一致するため、実行されないコードになります）。pathPrefix を使い、末尾のセグメントを自分で解析してください。各 http.route({...}) の handler: は、./_generated/server の httpAction(...) でラップする必要があります。単独の async (ctx, request) => {...} は型チェックに通りますが、有効な HTTP アクションではありません。
• ctx.runQuery／ctx.runMutation／ctx.runAction には、コード生成された関数参照（api.foo.bar／internal.foo.bar）が必要です。インポートしたモジュールメンバーをそのまま渡してはいけません（import * as queries from "./queries"; ctx.runQuery(queries.getX, ...) はコンパイルできますが、実行時に失敗します）。
• 自己検証ルール — バックエンド作業の完了を宣言する前に、コンパイルとプッシュを検証してください。npx tsc --noEmit を実行し、デプロイ環境にプッシュしてください。プロジェクトに既存のデプロイ環境があればそれを優先し、なければ npx convex whoami が成功する場合は npx convex dev --once を、それ以外の場合に限り CONVEX_AGENT_MODE=anonymous npx convex dev --once を実行してください。サインイン済みのユーザーに対して匿名モードを強制すると、.env.local が再バインドされ、ユーザーが期待している永続的で公開可能なクラウドデプロイ環境が失われます。報告されたエラーはすべて、完了前に修正してください。検証を一度行えば、そうしないとデプロイを壊す、相対インポートの誤り／シンボルの重複／括弧の不整合といった問題を検出できます。