ビルド設定

まずアプリのフレームワークを選び、iOS、Android、Capacitor の連携に使うビルドツールを設定します。フレームワークのガイドで Worker エントリーと実行境界を確認し、ツールのプラグインでそのエントリーをモバイルアプリへ接続します。既存の Cloudflare ビルドは分離して維持してください。

モバイルビルドには独立した設定と出力ディレクトリーを使います。プラグインはサーバーエントリーとデプロイ設定を読み、入力を変更せずモバイル用のコピーを生成します。Vite は SSR・サーバー環境と Cloudflare Vite プラグインを含む設定を拒否します。両ビルダーは既知のサーバー入力を含む出力先を拒否し、出力内の既存リンクも経由した書き込みを防ぐため拒否します。任意の Cloudflare デプロイディレクトリーを出力先に再利用しないでください。独自のビルドディレクトリーすべてを識別することはできません。OpenNext のルートコンパイルは .next と .open-next の外にある node_modules/.cache/workers-capacitor/opennext の一時ディレクトリーを使います。

このビルド境界により既存の Cloudflare デプロイを維持します。ローカル実行、リモートオリジン、getToken などの明示的なクライアント設定は、送信するリクエストと認証方法を制御しますが、サーバーのルート、認可処理、バインディングは変更しません。

ランタイムエントリーを選ぶ

バンドラープラグインはどのホストでも workersCapacitorPlugin です。変わるのはアプリのランタイムインポートだけで、Worker ソースと実行オプションは共通です。

cf-workers-native@0.1.2 と対応するネイティブ依存関係を使います。依存関係の設定を参照してください。各ターゲット用のエントリーをビルドし、出力ディレクトリー全体をパッケージに含めます。以下の既存の Capacitor 例は workersCapacitor を使いますが、SDK ホストの workersIOS と workersAndroid にも同じオプションが適用されます。

フレームワーク

次の統合にはサンプルと検証結果があります。サポート対象はここに記載した実行経路に限られます。API とアプリケーションの制約は互換性の制限を参照してください。

Hono

アプリケーションの既存の Fetch Handler を接続します。例:

import { Hono } from "hono";

const app = new Hono();
app.get("/", (c) => c.html("<h1>Hello from Hono</h1>"));
app.get("/api/hello", (c) => c.json({ hello: "world" }));
export default app;

Vite または esbuild プラグインの worker オプションにこのエントリーを指定します。Worker がページを所有する場合は render: "/" を使い、既存のフロントエンドを API と統合する場合は render を省略します。Capacitor の設定、クラウドバインディング、認証についてはアプリケーション統合ガイドに従ってください。

既定の execution: "network" から始め、baseURL にデプロイ済み Worker の HTTPS URL を設定します。remote.origin で別のデプロイ先を指定しなければ、そのオリジンを使います。選択した実装の端末への配布を許可するには execution にルート配列を指定します。Hono の /app/* などに対応します。許可は保持される依存データも含み、検出したサーバー境界は上書きしません。ローカルルートの選択を参照してください。

Workers Express

サンプルでは実際の express パッケージと Workers 形式のエントリーを使います。

import express from "express";
import { httpServerHandler } from "cloudflare:node";

const app = express();
app.use(express.json());
app.get("/api/hello", (_req, res) => res.json({ hello: "world" }));
app.listen(3000);
export default httpServerHandler({ port: 3000 });

Vite または esbuild プラグインはモバイル・ブラウザービルドだけに追加し、Cloudflare ビルドには使わないでください。ブラウザーポリフィルと Workers 互換の node:http・node:net アダプターを提供します。検証した基準とモジュールは互換性一覧を参照してください。listen(3000) はメモリー内ハンドラーを登録し、TCP ポートを開きません。Hono と Workers Express に対応し、フレームワークのコードは変更しません。

既定の execution: "network" は Worker 全体をリモートに維持します。workersCapacitor() の baseURL にデプロイ済み Worker の HTTPS URL を設定し、baseURL と異なるオリジンが必要な場合のみ remote.origin を指定します。意図的な単独動作の Express アプリでは、以下の Vite・esbuild オプションに execution: "local" を追加できます。これは Worker 実装全体と保持する固定データの配布を許可するため、サーバーの秘密情報を含めないでください。サーバーバインディングが設定されていれば local はビルドを失敗させます。実行方針を参照してください。

TypeScript の型

このパッケージは、対応する httpServerHandler アダプターの cloudflare:node 型を提供します。既存の Workers 型宣言がないブラウザビルドでは、tsconfig.json の compilerOptions.types に追加してください。

{ "compilerOptions": { "types": ["cf-workers-native/cloudflare/apis/types"] } }

プロジェクトですでに使っている他の型は残してください。これは型のみのエントリーであり、実行時にインポートしてはいけません。Workers の生成済み型を使うプロジェクトでは、その宣言を維持してください。アプリケーション側で cloudflare.d.ts や client.d.ts を用意する必要はありません。

Workers 上の Angular

この統合はまだ検証されていません。対象は、Cloudflare Workers にデプロイ済みの既存の Angular SSR アプリケーションです。Capacitor に移す際もレンダリング、ルーティング、ハイドレーションを維持することを目指しています。サポート対象に含めるには、専用の Worker エントリー設定と受け入れ検証用サンプルが必要です。

Vite または esbuild に対応しているだけでは、Angular SSR のサポートを意味しません。独立したフロントエンドの Fetch のみの統合は、別のユースケースです。

ツール

これらのバージョンは独立したモバイルビルドのものです。既存のクラウドビルドは別のツールやバージョンでも構いません。維持したまま、フレームワークのガイドに従って生成 Worker を接続してください。

他のバンドラーは現在非対応です。プラグインはモバイル・ブラウザービルドだけに追加し、Cloudflare ビルドには使わないでください。

Vite

モバイル・ブラウザー用の Vite 設定にプラグインを追加します。

import { defineConfig } from "vite";
import { workersCapacitorPlugin } from "cf-workers-native/tooling/vite";

export default defineConfig({
  plugins: [workersCapacitorPlugin({ worker: "./src/worker.ts" })],
});

src/worker.ts は Fetch Handler をエクスポートする既存のアプリケーションエントリー（Hono の export default app など）であり、ライブラリのトランスポートモジュールではありません。プラグインの worker パスは Vite のルートを基準に解決されます（絶対パスも使用できます）。プラグインがそのエントリーを通常のパッケージインポートに接続するため、アプリケーションコードで特殊なインポートや生成ソースファイルを使う必要はありません。

esbuild

esbuild では、同じアプリケーションコードに次のビルド設定を使用します。

import { build } from "esbuild";
import { workersCapacitorPlugin } from "cf-workers-native/tooling/esbuild";

await build({
  entryPoints: ["src/main.ts"],
  outdir: "www",
  bundle: true,
  format: "esm",
  platform: "browser",
  plugins: [workersCapacitorPlugin({ worker: "./src/worker.ts" })],
});

エントリーパスは absWorkingDir（またはカレントディレクトリ）を基準に解決されます。出力された Worker アセットや遅延読み込みされる direct モジュールを含む、出力ディレクトリ全体を配信してください。Worker のコンパイルにはプラグインの互換性変換を使用し、アプリケーションの追加プラグインは Worker バンドルには適用されません。outdir または outfile を指定したブラウザ ESM 出力が必要です。Worker エントリーは単一の JavaScript ファイルにバンドルする必要があり、個別の CSS / ファイルアセットには対応していません。

Browser ES Modules（バンドラーなし）

この経路は Fetch のみの統合向けであり、ネイティブドキュメント用アセットは自動で準備されません。バンドラーを使わない場合は、パッケージの dist ディレクトリを公開用の lib ディレクトリにコピーし、通常の相対 ES Module インポートを使用します。

// main.js（<script type="module"> で読み込み）
import { workersCapacitor } from "./lib/index.js";

const runtime = workersCapacitor({
  baseURL: "https://api.example.com/api/",
  worker: {
    createWorker: () =>
      new Worker(new URL("./worker-entry.js", import.meta.url), {
        type: "module",
      }),
    loadDirect: async () => (await import("./worker.js")).default,
  },
});
await runtime.ready;

// worker-entry.js
import { serve } from "./lib/browser/isolated/transport.js";
import worker from "./worker.js";
serve(worker);

worker.js は既存の Fetch Handler をエクスポートします。その依存関係もすべて、URL を解決可能なブラウザ互換の ES Modules でなければなりません。この経路では TypeScript、bare npm import、Node API、cloudflare:* インポートは変換されません。lib/browser/isolated/transport.js に相当する公開バンドル用エントリーは cf-workers-native/browser/isolated です。