本文へ移動

Astro、React Router、TanStack Start、Nuxt、SolidStart

対応する SSR フレームワークを、Arkor 専用の設定なしで Cloudflare Workers にデプロイします。

Markdown で表示

Arkor が推奨し、TTFB 改善の中心としているフレームワークは Next.js です。Partial Prerendering、ISR、Cache Components の統合により、動的レンダリングの完了前にキャッシュ済みコンテンツを配信できます。このページのフレームワークは、Cloudflare 向け Worker で SSR を実行し、クライアント用ファイルをネイティブ静的アセットとして配信します。

対応バージョン

フレームワーク対応する安定版とビルド
Astro>=6.0.0 <8。互換性のある公式 Cloudflare アダプターを使用
React Router>=7.10.0 <9。対応する Vite 6・7・8 を使う Framework Mode
TanStack StartReact・Solid ともに >=1.132.0 <2。アプリの互換 Vite を使用
Nuxt>=3.18.0 <5。Nuxt が実際に使う Nitro が >=2.12.0 <3
SolidStart>=1.1.0 <3。1 系は Vinxi >=0.5.3 <0.6 と Nitro 2 が必要

プレリリース、互換性のないプラグインの組み合わせ、不明なビルド内部構造は診断付きで停止します。アプリの依存バージョンと lockfile は変更しません。Vite 6・7・8 は各フレームワークの実際の依存が対応する組み合わせで利用できます。ブラウザーのルーターとしてだけ React Router を使うアプリや、Start を使わない TanStack Router は SSR と判定しません。SolidStart と Solid 版 TanStack Start は別のフレームワークです。この範囲は Arkor の統合範囲であり、上流の保守・セキュリティサポート期間を延長するものではありません。各フレームワークのリリース方針も確認してください。

Arkor 専用の設定なしでデプロイ

クイックスタートの手順でリポジトリーをインポートし、アプリのディレクトリーを選びます。Arkor は、そのアプリが宣言する依存関係とインストール済みのバージョンからフレームワークを識別します。選択したアプリが Next.js を宣言していれば Next.js を優先します。別のワークスペースにある hoist 済みの Next.js によって、SSR アプリを Next.js と判定することはありません。

Arkor のパッケージや設定ファイルは不要です。対応する公式デプロイ用の統合を、ビルド中に Cloudflare 向けへ適応します。ソースの設定を維持し、独自のビルドコマンドがあればそれを、なければ既存のビルドスクリプトを、どちらもなければフレームワークのビルドコマンドを使います。ビルドとデプロイも参照してください。

既存の Cloudflare エントリーポイントや Wrangler 設定もビルドの入力として使います。ビルド後に生成された Wrangler 設定から Worker とアセットの場所を読み取るため、出力ディレクトリーを変更したプロジェクトにも対応できます。コマンドが成功しても Node.js サーバーしか残っていなければデプロイできません。不明なアダプターやプロバイダー用プラグインは、出力の実行方法を推測せずエラーにします。

Nitro Vite プラグインから直接 Worker へ移行する場合は、対応する公式 SSR preset とビルドログの設定を受け入れます。実行時の Nitro 設定や、nitro.config.*、.config/ 内の Nitro 設定、.nitrorc などの独立した設定ファイルは、振る舞いを自動で維持できないためエラーにします。この制限は、Nuxt がネイティブに使う Nitro 設定には適用しません。

フレームワーク別の動作

Astro

対応する公式 Astro アダプターを Cloudflare 向けにビルドし、事前生成したファイルとオンデマンドのルートを維持します。ホスト側で Images の可用性を確認済みの場合、画像が未設定なら { build: 'compile', runtime: 'cloudflare-binding' } を補完し、ビルド時はローカルでコンパイル、実行時は管理された Images で変換します。明示された compile・passthrough・独自サービスは維持します。既定バインディングの自動付与が無効なら、IMAGES を明示登録するか、アダプターで登録済みの独自名を選んでください。権限不足やホスト側の利用不可は診断します。Images 変換も参照してください。

インストール済み Astro に応じて、6.0–6.2 は 13.3.1、6.3 以降は 13.7.0、7.0–7.1 は 14.1.7、7.2–7.3 は 14.2.0、7.4 以降は 14.4.0 の公式アダプターをビルド専用に選びます。13.4.0 と 14.2.0 は peer 範囲にかかわらず Astro 6.0・7.0 にない実行時 API を参照するため、それぞれ 13.3.1・14.1.7 を使います。14.3.x も Astro 7.2 にないプリレンダー API を必要とするため、その範囲には 14.2.0 を選びます。アプリのソースにはインストールしません。

Cloudflare による明示的なビルド時画像変換は対象外です。アダプター 14.3.2 以降の文字列 imageService: 'cloudflare-binding' はビルド時変換も含むため、上記の compound 設定へ変更してください。それ以前の文字列は実行時専用の意味を持ちます。元のインストール済みアダプターのバージョンを確認し、ビルド用の新しい版へ移すことで意味が変わる場合は、Cloudflare のビルド時変換を黙って有効にせず、compound 設定への変更を案内します。独自の binding 名は維持し、IMAGES を必要とする版には同じ権限のローカル alias を渡します。名前が衝突する場合は公開を停止します。

暗黙のセッション用 KV は、Arkor 管理の SESSION、UPWIND_KV、それ以外に KV が 1 つだけあればそのバインディング、の順に選びます。不足や曖昧な選択はエラーにします。明示した driver・binding、セッションの無効化、Cookie、TTL の設定は維持します。KV の名前を明示した場合は、管理対象のバインディングと一致させてください。ローカルのデプロイ CLI は、既定のバインディングの自動作成が有効で KV がない場合、通常の既定値である UPWIND_KV を作成できます。公式の Cloudflare アダプターガイドも参照してください。

Astro の workerd プリレンダー環境は、ビルド時に Node.js を必要とします。Astro CLI の Node.js shebang を維持するため、--bun を付けずに bun run build を使うか、Node.js で Astro CLI を実行してください。Cloudflare と Bun のリクエストが停止する問題が残っている間、このプリレンダー環境を Bun で直接実行する構成はサポートしません。

React Router

React Router 7 の future.v8_viteEnvironmentApi と future.v8_middleware は維持します。旧ビルド方式は公式の解決済み設定と完了 hook を、Environment API 方式は Cloudflare Vite 統合を使います。loader、action、サーバーレンダリング、クライアント用ファイルはフレームワークの動作を維持します。RSC、ssr: false・SPA モード、prerender、serverBundles はこの SSR 統合の対象外です。React Router のデプロイガイドも参照してください。

loader や action では、cloudflare:workers から env と waitUntil をインポートし、管理対象のバインディングやバックグラウンド処理を使えます。middleware 無効の React Router 7 は plain load context を使い、有効な 7 と React Router 8 はリクエストごとの RouterContextProvider を使います。middleware でアプリが定義した createContext のキーに値を設定し、loader や action で context.get を使って取得します。独自の context 初期化を含む、明示した既存の Worker エントリーポイントは維持します。

TanStack Start

React 版と Solid 版の両方で、Vite ビルドと Cloudflare Worker の出力を使い、server function とクライアント用アセットを維持します。事前生成した公開ファイルもネイティブアセットとして配信します。Rsbuild や実験的な RSC ビルドはサポートしません。TanStack Start のホスティングガイドも参照してください。

Nuxt

ビルド中に Nitro の cloudflare_module preset を選択します。通常は Node.js や対応する別の公式プロバイダーを対象としているアプリも含みます。Nitro が生成する設定からサーバーと公開アセットの場所を読み取り、.output に固定しません。Nuxt がネイティブに使う Nitro の設定は維持します。独自・静的出力専用・リソース専用の preset は、その hook や振る舞いを破棄せずエラーにします。別の server builder や Nitro 3 を明示的に使う構成には、対応する Cloudflare Worker の出力が必要で、標準の Nitro 2 統合では保証しません。Nitro 2 の Cloudflare ガイドも参照してください。

SolidStart

SolidStart 1 は Vinxi/Nitro を使い、既存 hook と実際の Rollup entry を維持します。Wrangler writer のない旧 Nitro では、成功した今回のビルドから一時領域に設定を生成します。SolidStart 2 は Vite の server environment と公式 Cloudflare プラグインで SSR を実行します。対応する公式の Node・Nitro・Netlify 統合はビルド中に適応します。独自の server runtime や静的出力だけのビルドは、この SSR 統合の対象外です。SolidStart のデプロイ用プラグインも参照してください。

バインディング・配信・制限

環境変数、シークレット、管理対象の KV・R2・D1 は Arkor で設定します。宣言されたバインディングの名前と種類は、そのサービスへの割り当てと一致させてください。割り当て時のバインディング名は、元のリソース名と異なっていてもかまいません。既存の Cloudflare リソース ID はインポートしません。プロジェクトの環境変数とシークレットは、同名の Wrangler 変数より優先します。ネイティブの契約はバインディングと Hono と fetch ハンドラーを参照してください。

streaming body、リダイレクト、Cookie を含むレスポンスは SSR アプリが制御します。Arkor はレンダリングの完了を待たずに転送し、個人向けの HTML に共有キャッシュを追加しません。Next.js のキャッシュ済みシェルの再開や ISR の経路は使いません。ビルドの検査にはフレームワーク、インストール済みバージョン、ネイティブアセット数を表示します。ソースのルートツリーと実行時の Cache タブは Next.js の機能です。

各サービスでアプリ用 Worker 1 つとそのアセットをビルドします。複数のアプリをまとめてデプロイする場合や、非公開で接続する場合は、Arkor のサービスとリリースで設定します。既存の Wrangler の service binding はインポートしません。Worker の scheduled() ハンドラーと triggers.crons による定期実行にも対応します。Cron ジョブを参照してください。

このフレームワーク統合には、Durable Object のクラスの公開、queue、その他のイベントトリガーの作成は含みません。Node.js 専用の依存パッケージや待ち受けるサーバーには、Workers で動くための変更が必要な場合があります。未対応のモードや、不足・衝突するバインディングは、ビルド中または公開前に報告します。トラブルシューティングも参照してください。