Build-Einrichtung

Wählen Sie zuerst das Framework Ihrer Anwendung und konfigurieren Sie anschließend das Buildwerkzeug für die iOS-, Android- oder Capacitor-Integration. Die Framework-Anleitung bestimmt Worker-Einstiegspunkt und Ausführungsgrenze; das Werkzeug-Plugin verbindet diesen Einstiegspunkt mit der mobilen App. Halten Sie den bestehenden Cloudflare-Build getrennt.

Verwenden Sie für den mobilen Build eine separate Konfiguration und ein separates Ausgabeverzeichnis. Das Plugin liest Server-Einstiegspunkt und Deployment-Konfiguration und erzeugt eine mobile Kopie, ohne diese Eingaben umzuschreiben. Vite weist SSR-/Serverumgebungen und Konfigurationen mit dem Cloudflare-Vite-Plugin zurück. Beide Builder weisen Ausgabeverzeichnisse mit bekannten Servereingaben zurück; bestehende Links darin werden abgewiesen, um Schreibzugriffe durch sie zu verhindern. Verwenden Sie kein beliebiges Cloudflare-Deployment-Verzeichnis als mobile Ausgabe: Das Plugin kann nicht jedes eigene Buildverzeichnis erkennen. Die OpenNext-Routenkompilierung verwendet ein temporäres Verzeichnis in node_modules/.cache/workers-capacitor/opennext, außerhalb von .next und .open-next.

Diese Buildgrenzen erhalten das bestehende Cloudflare-Deployment. Explizite Cliententscheidungen wie lokale Ausführung, Remote-Origin und getToken steuern weiterhin, welche Anfragen es erreichen und wie sich der Client authentifiziert; sie ändern weder Serverrouten noch Autorisierungslogik oder Bindings.

Laufzeiteinstiegspunkt wählen

Das Bundler-Plugin heißt bei jedem Host weiterhin workersCapacitorPlugin. Nur der Laufzeitimport der Anwendung ändert sich; Worker-Quellcode und Ausführungsoptionen werden gemeinsam verwendet.

Verwenden Sie cf-workers-native@0.1.2 mit passenden nativen Abhängigkeiten; siehe Abhängigkeiten einrichten. Erstellen Sie für jedes Ziel den entsprechenden Einstiegspunkt und verpacken Sie anschließend das gesamte Ausgabeverzeichnis. Die folgenden bestehenden Capacitor-Beispiele verwenden workersCapacitor; dieselben Optionen gelten für workersIOS und workersAndroid in ihren SDK-Hosts.

Frameworks

Für die folgenden Integrationen liegen Beispiele und Verifizierungsnachweise vor. Die Unterstützung beschränkt sich auf die hier beschriebenen Ausführungspfade; API- und Anwendungseinschränkungen finden Sie unter Kompatibilitätsgrenzen.

Hono

Binden Sie den vorhandenen Fetch Handler der Anwendung ein. Zum Beispiel:

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;

Richten Sie die Option worker des Vite- oder esbuild-Plugins auf diesen Einstiegspunkt. Verwenden Sie render: "/" für Seiten des Workers oder lassen Sie render weg, wenn Sie ein vorhandenes Frontend mit der API verbinden. Folgen Sie der Anleitung zur Anwendungsintegration für Capacitor-Einrichtung, Cloud-Bindings und Authentifizierung.

Beginnen Sie mit dem Standard execution: "network" und setzen Sie baseURL auf die HTTPS-URL des bereitgestellten Workers. Remote-Anfragen verwenden deren Origin, sofern Sie nicht ausdrücklich einen anderen bereitgestellten Origin unter remote.origin angeben. Um ausgewählte Implementierungen auf dem Gerät ausliefern zu dürfen, setzen Sie execution auf ein Routenarray. Hono-Pfade wie /app/* werden unterstützt. Die Erlaubnis umfasst beibehaltene Abhängigkeitsdaten und hebt erkannte Servergrenzen nicht auf. Siehe lokale Routenauswahl.

Workers Express

Das Beispiel verwendet das echte Paket express und den Workers-Einstiegsstil:

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 });

Verwenden Sie das Vite- oder esbuild-Plugin ausschließlich im mobilen/Browser-Build, niemals im Cloudflare-Build. Es liefert Workers-kompatible Adapter für node:http und node:net neben Browser-Polyfills; das Kompatibilitätsverzeichnis dokumentiert verifizierte Basis und Module. listen(3000) registriert einen Handler im Speicher, keinen lauschenden TCP-Port. Das Plugin unterstützt Hono und Workers Express; Framework-Code bleibt unverändert.

Der Standard execution: "network" belässt den Worker vollständig remote. Setzen Sie baseURL in workersCapacitor() auf die HTTPS-URL des bereitgestellten Workers; setzen Sie remote.origin nur, wenn der Remote-Origin vom Origin von baseURL abweichen muss. Ergänzen Sie für eine bewusst eigenständige Express-App execution: "local" in den folgenden Vite- oder esbuild-Plugin-Optionen. Dies erlaubt die Auslieferung der gesamten Worker-Implementierung und beibehaltener fester Daten auf das Gerät; verwenden Sie es nicht mit Servergeheimnissen. Konfigurierte Server-Bindings lassen local beim Build fehlschlagen. Siehe Ausführungsrichtlinien.

TypeScript-Typen

Das Paket stellt den Typ für cloudflare:node für seinen unterstützten Adapter httpServerHandler bereit. Fügen Sie ihn für einen Browser-Build ohne vorhandene Workers-Typdeklarationen zu compilerOptions.types in tsconfig.json hinzu:

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

Behalten Sie alle anderen bereits verwendeten Typen bei. Dieser Einstiegspunkt dient nur der Typisierung; importieren Sie ihn nicht zur Laufzeit. Projekte mit generierten Workers-Typen sollten stattdessen diese Deklarationen behalten. Eine anwendungseigene cloudflare.d.ts oder client.d.ts ist nicht erforderlich.

Angular auf Workers

Diese Integration ist noch nicht verifiziert. Das Ziel ist eine bestehende Angular-SSR-Anwendung, die auf Cloudflare Workers bereitgestellt ist und deren Rendering, Routing und Hydration bei der Übernahme in Capacitor erhalten bleiben. Eine dedizierte Konfiguration des Worker-Einstiegspunkts und ein Abnahmebeispiel sind noch erforderlich, bevor sie als unterstützt aufgeführt werden kann.

Die Unterstützung von Vite oder esbuild allein weist keine Angular-SSR-Unterstützung nach. Die reine Fetch-Integration eines separaten Frontends ist ein anderer Anwendungsfall.

Werkzeuge

Diese Versionen beschreiben den separaten mobilen Build. Der bestehende Cloud-Build eines Frameworks kann ein anderes Werkzeug oder eine andere Version verwenden; lassen Sie ihn unverändert und verbinden Sie seinen generierten Worker gemäß der Framework-Anleitung.

Andere Bundler werden derzeit nicht unterstützt. Fügen Sie diese Plugins ausschließlich dem mobilen/Browser-Build hinzu, niemals dem Cloudflare-Build.

Vite

Fügen Sie das Plugin zur mobilen/Browser-Vite-Konfiguration hinzu:

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

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

src/worker.ts ist der vorhandene Anwendungseinstiegspunkt, der einen Fetch Handler exportiert (zum Beispiel Honos export default app), kein Transportmodul der Bibliothek. Der Pfad worker des Plugins ist relativ zum Vite-Stammverzeichnis (absolute Pfade funktionieren ebenfalls). Das Plugin verbindet diesen Einstiegspunkt mit dem normalen Paketimport; im Anwendungscode ist weder ein spezieller Import noch eine generierte Quelldatei nötig.

esbuild

Verwenden Sie für esbuild denselben Anwendungscode mit dieser Build-Konfiguration:

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" })],
});

Der Einstiegspfad ist relativ zu absWorkingDir (oder zum aktuellen Verzeichnis). Stellen Sie das gesamte Ausgabeverzeichnis bereit, einschließlich erzeugter Worker-Assets und verzögert geladener direkter Module. Die Worker-Kompilierung verwendet die Kompatibilitätstransformationen des Plugins; zusätzliche Anwendungsplugins werden nicht auf das Worker-Bundle angewendet. Browser-ESM-Ausgabe mit outdir oder outfile ist erforderlich. Worker-Einstiegspunkte müssen in eine einzelne JavaScript-Datei gebündelt werden; separate CSS-/Datei-Assets werden nicht unterstützt.

Browser ES Modules (ohne Bundler)

Dieser Weg dient der reinen Fetch-Integration und bereitet native Dokument-Assets nicht automatisch vor. Kopieren Sie ohne Bundler das Verzeichnis dist des Pakets in Ihr öffentliches Verzeichnis lib und verwenden Sie gewöhnliche relative ES-Module-Importe:

// main.js (geladen mit <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 exportiert den vorhandenen Fetch Handler. Alle seine Abhängigkeiten müssen ebenfalls browserkompatible ES Modules mit auflösbaren URLs sein. Dieser Weg transformiert weder TypeScript, bloße npm-Importe, Node-APIs noch cloudflare:*-Importe. Das öffentliche gebündelte Gegenstück zu lib/browser/isolated/transport.js ist cf-workers-native/browser/isolated.