convex-components

Convex Components を使用して、分離されたバックエンド機能を追加し、コンポーネント API を組み合わせます。 - **コンポーネントの概要**：https://docs.convex.dev/components - **理解する**：https://docs.convex.dev/components/understanding - **使用する**：https://docs.convex.dev/components/using - **作成する**：https://docs.convex.dev/components/authoring - **ディレクトリ**：https://convex.dev/components 特定のコンポーネントについては、次のリファレンスファイルを参照してください。 - `references/agent.md` — Agent コンポーネント：スレッド／メッセージ、ストリーミング、ツール、コンテキスト、デバッグ、使用状況の追跡、インストール／セットアップ。 - `references/rag.md` — RAG コンポーネント：名前空間、add/search/generateText、フィルター、チャンク化、プロンプト RAG とツール RAG。 - `references/workpool.md` — Workpool コンポーネント：キューへの追加、再試行、onComplete、並列処理、バッチ処理、モニタリング。 - `references/workflow.md` — Workflow コンポーネント：永続的なステップ、イベント、再試行、ステータス、キャンセル／クリーンアップ、制限。

メンタルモデル

• コンポーネントは、それぞれ独自のスキーマ、テーブル、ファイルストレージ、関数を持つ、分離された小規模なバックエンドです。
• コンポーネントは、明示的に渡されない限り、アプリのテーブル／関数／環境変数にアクセスしてはなりません。
• コンポーネントへの呼び出しは呼び出し元と同じトランザクション内で行われますが、コンポーネントのミューテーションはサブトランザクションです。

コンポーネントのインストール

• パッケージをインストールします：npm i @convex-dev/<component>。
• convex/convex.config.ts を追加します：
  • import { defineApp } from "convex/server";
  • app.use(component) を使用します。複数のインスタンスには app.use(component, { name: "custom" }) を使用します。
• コンポーネントコードを生成するには、必ず npx convex dev を実行してください。
• convex/_generated/api の components.<name> を使用してアクセスします。

コンポーネント API の呼び出し

• components.<name>.<fn> とともに ctx.runQuery/Mutation/Action を使用します。
• コンポーネントの公開関数は内部参照であるため、クライアントから直接呼び出してはなりません。
• クエリは引き続きリアクティブです。ミューテーションはトランザクションとして実行されます。

トランザクションのセマンティクス

• トップレベルのミューテーションは、すべてのコンポーネントにまたがる書き込みをまとめてコミットします。
• コンポーネントのミューテーションが例外をスローした場合、ロールバックされるのはそのコンポーネントの書き込みのみです。呼び出し元は例外を捕捉して処理を続けてもかまいません。

コンポーネント API の違い

• components.<name> で公開されるのは、コンポーネントの公開関数のみです。
• Id 型は境界を越えると string になります。外部テーブルに v.id("table") を使用してはなりません。
• 各コンポーネントには独自の _generated ディレクトリがあります。アプリの components 参照を使用してください。

環境変数

• コンポーネントは process.env に直接アクセスしてはなりません。
• 環境変数の値はアプリから引数として渡すか、コンポーネントのテーブルに設定を保存してください。

HTTP アクション

• コンポーネントはルートを直接公開してはなりません。アプリは convex/http.ts でハンドラーをマウントする必要があります。

コンポーネントでの認証

• コンポーネント関数内では ctx.auth を使用できません。
• アプリで認証を行い、識別子（userId）をコンポーネント関数に渡してください。

ページネーション

• コンポーネント内では組み込みの .paginate() はサポートされていません。
• 必要に応じて、convex-helpers のページネーターと convex-helpers の usePaginatedQuery を使用してください。

コンポーネントの作成

• コンポーネントのフォルダーには、convex.config.ts、schema.ts、関数、_generated を含める必要があります。
• defineComponent("name") でコンポーネントを定義します。子コンポーネントには component.use(...) を使用します。
• ローカルコンポーネントは convex/components/ または任意のフォルダーに配置できます。
• NPM コンポーネントでは、次のものをエクスポートすることを推奨します：
  • @pkg/convex.config.js
  • @pkg/_generated/component.js
  • @pkg/test ヘルパー

関数ハンドル

• 境界を越えてコールバックを渡すには、createFunctionHandle(api.foo.bar) を使用することを推奨します。
• ハンドルは文字列です。v.string() バリデーターを使用し、FunctionHandle にキャストして戻します。

コンポーネントのテスト

• コンポーネントのスキーマ／モジュール、または提供されているテストヘルパーを使って、convex-test にコンポーネントを登録することを推奨します。
• コンポーネントのパッケージでは、@pkg/test の登録ヘルパーを使用することを推奨します。

ベストプラクティス

• 公開コンポーネント関数では、必ず引数と戻り値を検証してください。
• コンポーネント API を再エクスポートする際は、認証やレート制限を追加するために、アプリケーションレベルのラッパーを使用することを推奨します。
• 静的な設定には、1 行のグローバル／設定テーブルを使用することを推奨します。