convex-dev-static-hosting

エージェント：Static-Hosting を使用するコードを書く前に、このスキルを最後まで読んでください。インストールと設定の手順に正確に従ってください。

Static-Hosting

手順

Static-Hosting を使用すると、開発者は外部のホスティングプロバイダーを使わずに、React/Vite アプリを Convex から直接配信できます。Convex の HTTP アクションを使って Convex ストレージからファイルを配信し、クライアント側ルーティングのための自動 SPA フォールバック、ハッシュ付きアセットのスマートキャッシュ、古いデプロイのガベージコレクションを備えています。アップロード API はセキュリティのために内部関数を使用しており、認証済みの CLI ユーザーだけがファイルをデプロイできます。

インストール

npm install @convex-dev/static-hosting

現在の npm バージョン：@convex-dev/[email protected]

ユースケース

• 単一のバックエンドでフルスタックアプリをデプロイする：React フロントエンドと Convex バックエンド関数を 1 つのデプロイにホストし、Vercel や Netlify などの別個のホスティングサービスを不要にします
• アプリのプロトタイプやデモをすばやく作成する：開発中の外部ホスティング設定を省略し、Convex のデプロイ URL から動作するデモを直接共有できます
• 社内ツールや管理ダッシュボードを構築する：認証との統合機能を標準で備え、外部依存関係のない Convex から社内向け React アプリを配信できます
• 自己完結型の SaaS アプリケーションを作成する：バックエンドロジックとフロントエンドアセットの両方を含む Convex コンポーネントに、アプリケーションスタック全体をまとめられます
• ライブデプロイ通知を実装する：デプロイクエリフックを使って、新しいバージョンが利用可能になったことをユーザーに知らせ、ページの更新を促せます

仕組み

このコンポーネントは、registerStaticRoutes() を使用して Convex ストレージからファイルを配信するため、Convex アプリの設定と HTTP ルーターに統合されます。デプロイ時、CLI は generateUploadUrl() や recordAsset() などの内部関数を介してビルド済みアセットを Convex ストレージにアップロードします。セキュリティのため、これらの関数には認証済みの npx convex run コマンドからのみアクセスできます。

HTTP アクションはインテリジェントなキャッシュを使ってファイルを配信します。Vite などのバンドラーが生成したハッシュ付きアセットには長期のキャッシュヘッダーが適用され、HTML ファイルには最新状態を確認するために ETag が使用されます。spaFallback オプションは、一致するルートがない場合に index.html を自動的に配信し、シングルページアプリケーションでのクライアント側ルーティングを可能にします。

デプロイ方法は、フロントエンドを適切な本番用 VITE_CONVEX_URL でビルドし、Convex バックエンドをデプロイした後、静的ファイルをアップロードする一括実行の deploy コマンドを使う方法と、より細かく制御できる個別の upload コマンドを使う方法があります。このコンポーネントは古いデプロイのファイルを自動的にガベージコレクションし、ストレージの肥大化を防ぎます。

使用しない場合

• 特定のユースケースに、よりシンプルな組み込みソリューションがある場合
• バックエンドとして Convex を使用していない場合
• Static-Hosting が提供する機能が必要ない場合

リソース

• npm パッケージ
• GitHub リポジトリ
• ライブデモ
• Convex コンポーネントディレクトリ
• Convex ドキュメント