@takazudo/zfb-adapter-cloudflare 0.1.0-next.2

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0-next.1
+
+Initial public prerelease on npm.
+
+- Cloudflare Pages adapter for zfb static sites.
+- `bin: zfb-adapter-cloudflare` wraps the build into a Worker-deployable bundle.
+- Subpath exports: `build`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @takazudo/zfb-adapter-cloudflare
+
+> Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary.
+
+The Cloudflare Pages adapter for [zfb][zfb-site]. Wraps the
+`@takazudo/zfb-runtime` page router into a Cloudflare Pages advanced-mode
+`_worker.js` entry, threading `(env, ctx)` through to user code via
+`AsyncLocalStorage`.
+
+This package is the Cloudflare half of the SSR adapter contract. Other
+targets (Node, Netlify, …) will land as sibling `@takazudo/zfb-adapter-*`
+packages with the same shape.
+
+Full documentation: <https://takazudomodular.com/pj/zudo-front-builder/>.
+Source: <https://github.com/Takazudo/zudo-front-builder>.
+
+[zfb-site]: https://takazudomodular.com/pj/zudo-front-builder/
+
+## Install
+
+```sh
+npm install --save-dev @takazudo/zfb-adapter-cloudflare
+# or: pnpm add -D @takazudo/zfb-adapter-cloudflare
+```
+
+## Usage
+
+In `zfb.config.json`:
+
+```jsonc
+{
+  "framework": "preact",
+  "adapter": "@takazudo/zfb-adapter-cloudflare"
+}
+```
+
+Then in any page that needs Cloudflare bindings — secrets, KV, or a
+D1 database:
+
+```ts
+// pages/api/products.tsx
+import { getCloudflareContext } from "@takazudo/zfb-adapter-cloudflare";
+
+export const prerender = false; // opt out of build-time SSG
+
+interface Env {
+  ANTHROPIC_API_KEY: string;
+  DB: D1Database; // a `wrangler.toml` D1 binding named "DB"
+}
+
+export default async function Products() {
+  const { env, ctx } = getCloudflareContext<Env>();
+  ctx.waitUntil(reportToAnalytics());
+  // A D1 binding is just-another-object on `env` — query it directly.
+  const { results } = await env.DB.prepare("SELECT * FROM products").all();
+  return new Response(JSON.stringify(results), {
+    headers: { "content-type": "application/json" },
+  });
+}
+```
+
+See the [SSR and Cloudflare Bindings guide][ssr-guide] for the full D1
+lifecycle (`wrangler d1 create`, migrations, preview-vs-prod).
+
+[ssr-guide]: https://takazudomodular.com/pj/zudo-front-builder/guides/ssr-and-cloudflare-bindings/
+
+`zfb build` will:
+
+1. Render every SSG page (`prerender !== false`) into static HTML under
+   `dist/`.
+2. Hand the SSR bundle to this adapter, which writes
+   `dist/_worker.js` (the wrapper) and `dist/_zfb_inner.mjs` (the
+   bundle) ready to be deployed via Cloudflare Pages advanced mode.
+
+## CLI
+
+The package ships a `zfb-adapter-cloudflare` bin invoked by
+`zfb-build`:
+
+```
+zfb-adapter-cloudflare bundle <input.mjs> --outdir dist/
+```
+
+`<input.mjs>` is the ESM bundle `zfb-build`'s bundler emits. The
+output is a single Workers-shaped entry plus a sidecar copy of the
+inner bundle.
+
+## Why two files
+
+The wrapper imports the inner bundle by relative path
+(`./_zfb_inner.mjs`) instead of inlining it, so the adapter package
+itself does not need to ship an esbuild binary. Workerd's Module
+loader resolves relative ESM imports inside an advanced-mode
+`_worker.js` directory layout.
+
+## Why AsyncLocalStorage on a globalThis registry
+
+Cloudflare Workers can dispatch multiple requests concurrently in the
+same isolate, so reading `env` from `globalThis` would race across
+requests. AsyncLocalStorage gives each request its own scope.
+
+We register the storage instance on `globalThis` under a stable key so
+the wrapper at `_worker.js` and the user pages bundled together share
+the same instance even when this module ends up duplicated in the
+final module graph (the wrapper and the user bundle are separate ESM
+graphs by design).
+
+## Acceptance test
+
+`src/__tests__/cli.test.ts` imports the produced `_worker.js`
+directly into vitest, builds a synthetic `Request + env + ctx`, and
+asserts that user code reading `env.ANTHROPIC_API_KEY` sees the value
+the wrapper passed in. This stands in for a full `wrangler dev` smoke
+test, which would require port binding and is out of scope for the
+worktree-side test loop.

package/bin/cli.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+//
+// `zfb-adapter-cloudflare` CLI.
+//
+// Subcommands:
+//
+//   bundle <input> --outdir <dir>
+//
+//     Wrap the input ESM bundle into a Cloudflare Pages `_worker.js`
+//     placed under <dir>. The input bundle is the file `zfb_build`'s
+//     bundler emits; <dir> is typically the project's `dist/`.
+//
+// The CLI is intentionally tiny and dependency-free. It imports the
+// wrapper string from the canonical `src/worker-wrapper.mjs` (plain JS,
+// no TypeScript loader required) so there is a single source of truth.
+// invariant: no runtime npm deps — see SECURITY-DEPS.md
+
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Wrapper source — imported from the single canonical source.
+// ---------------------------------------------------------------------------
+
+import { WORKER_WRAPPER_SOURCE } from "../src/worker-wrapper.mjs";
+export { WORKER_WRAPPER_SOURCE };
+
+export async function emitWorker({ inputBundlePath, outdir }) {
+  const outdirAbs = resolve(outdir);
+  const inputAbs = resolve(inputBundlePath);
+
+  await mkdir(outdirAbs, { recursive: true });
+  const innerBundlePath = join(outdirAbs, "_zfb_inner.mjs");
+  await copyFile(inputAbs, innerBundlePath);
+
+  const workerPath = join(outdirAbs, "_worker.js");
+  await writeFile(workerPath, WORKER_WRAPPER_SOURCE, "utf8");
+
+  return { workerPath, innerBundlePath };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function fail(message) {
+  process.stderr.write(`zfb-adapter-cloudflare: ${message}\n`);
+  process.exit(1);
+}
+
+function printUsage() {
+  process.stdout.write(`Usage:
+  zfb-adapter-cloudflare bundle <input> --outdir <dir>
+
+Wrap an ESM bundle (the output of zfb-build's bundler) into a
+Cloudflare Pages \`_worker.js\` placed under <dir>.
+
+Options:
+  --outdir <dir>    Output directory. Required.
+  -h, --help        Show this help.
+`);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+    return { command: "help" };
+  }
+  const command = args[0];
+  if (command !== "bundle") {
+    fail(`unknown subcommand: ${command}\nRun \`zfb-adapter-cloudflare --help\` for usage.`);
+  }
+
+  let input = null;
+  let outdir = null;
+  let i = 1;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--outdir") {
+      const next = args[i + 1];
+      if (!next) fail("--outdir requires a directory argument");
+      outdir = next;
+      i += 2;
+      continue;
+    }
+    if (arg.startsWith("--outdir=")) {
+      outdir = arg.slice("--outdir=".length);
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      fail(`unknown option: ${arg}`);
+    }
+    if (input === null) {
+      input = arg;
+      i += 1;
+      continue;
+    }
+    fail(`unexpected positional argument: ${arg}`);
+  }
+
+  if (!input) fail("missing required positional argument: <input>");
+  if (!outdir) fail("missing required option: --outdir <dir>");
+
+  return { command: "bundle", input, outdir };
+}
+
+async function main() {
+  // Skip when imported (e.g. by the vitest that snapshots
+  // WORKER_WRAPPER_SOURCE). When this file is run directly the process
+  // entry resolves (after symlinks) to this file's realpath.
+  //
+  // pnpm's `.bin` shim invokes `node node_modules/.bin/../<pkg>/bin/cli.mjs`,
+  // so `process.argv[1]` lexically resolves to the symlinked
+  // `node_modules/<pkg>/bin/cli.mjs` path — but Node's ESM loader follows
+  // symlinks by default, so `import.meta.url` points at the realpath under
+  // `.pnpm/`. A lexical compare therefore mismatches under pnpm exec and
+  // the CLI silently no-ops. Compare realpaths so direct `node bin/cli.mjs`,
+  // pnpm exec, npm bin shims, and Yarn PnP all agree.
+  const entry = process.argv[1];
+  if (!entry) return;
+  let entryReal;
+  let selfReal;
+  try {
+    entryReal = realpathSync(entry);
+    selfReal = realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return; // can't resolve either side — treat as imported, not run
+  }
+  if (entryReal !== selfReal) return;
+
+  const parsed = parseArgs(process.argv);
+  if (parsed.command === "help") {
+    printUsage();
+    return;
+  }
+
+  const inputAbs = resolve(process.cwd(), parsed.input);
+  const outdirAbs = resolve(process.cwd(), parsed.outdir);
+  const out = await emitWorker({
+    inputBundlePath: inputAbs,
+    outdir: outdirAbs,
+  });
+  process.stdout.write(`wrote ${out.workerPath}\nwrote ${out.innerBundlePath}\n`);
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+  fail(msg);
+});

package/dist/build.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The wrapper source written to `_worker.js`. Imported from the single
+ * canonical `.mjs` file so `src/build.ts` and `bin/cli.mjs` always stay
+ * in sync without any duplication.
+ */
+export declare const WORKER_WRAPPER_SOURCE: string;
+/**
+ * Inputs to [`emitWorker`].
+ */
+export interface EmitWorkerInput {
+    /**
+     * Absolute path to the input ESM bundle produced by `zfb-build`. The
+     * bundle must export a Workers-shaped `default { fetch: (request) =>
+     * Promise<Response> }` (this is the contract `zfb_build::bundler`
+     * pins). The file is copied verbatim next to the emitted wrapper so
+     * relative imports inside it keep resolving.
+     */
+    readonly inputBundlePath: string;
+    /**
+     * Absolute path to the output directory. The emitter creates it if
+     * missing and writes `_worker.js` plus `_zfb_inner.mjs` (the copied
+     * input bundle) into it.
+     */
+    readonly outdir: string;
+}
+/**
+ * Output paths the emitter produced. Returned for callers that want to
+ * log them (the Rust orchestrator surfaces them in build output).
+ */
+export interface EmitWorkerOutput {
+    readonly workerPath: string;
+    readonly innerBundlePath: string;
+}
+/**
+ * Emit a Cloudflare Pages `_worker.js` that wraps the zfb input bundle.
+ *
+ * Output shape (two files in `outdir`):
+ *
+ *   _worker.js       — entry imported by Cloudflare Pages advanced mode
+ *   _zfb_inner.mjs   — the input bundle, copied verbatim
+ *
+ * The wrapper imports the inner bundle via the relative path
+ * `./_zfb_inner.mjs`. Workerd's Module loader resolves relative ESM
+ * imports inside an advanced-mode `_worker.js` directory, so this layout
+ * works without re-bundling.
+ *
+ * Why two files instead of one: re-bundling here would require a second
+ * esbuild pass and would force the adapter to ship its own esbuild
+ * binary slot. The two-file layout keeps the adapter dependency-free at
+ * runtime — it is just `node:fs` glue.
+ */
+export declare function emitWorker(input: EmitWorkerInput): Promise<EmitWorkerOutput>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAA2B,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAelF"}

package/dist/build.js

@@ -0,0 +1,49 @@
+// `@takazudo/zfb-adapter-cloudflare/build` — Node-only build helpers.
+//
+// This sub-entry is intentionally **not** imported by the Workers-runtime
+// entry (`./`). Code in this module may freely use Node built-ins
+// (`node:fs`, `node:path`, …) because it only ever runs in a Node 22+
+// build environment, never inside a Cloudflare Worker isolate.
+//
+// The `./` entry (`src/index.ts`) exports only Workers-runtime-safe code
+// (AsyncLocalStorage helpers) that can be bundled into the worker.
+// @ts-expect-error worker-wrapper.mjs has no declaration file; the export
+// shape is narrowed explicitly below.
+import { WORKER_WRAPPER_SOURCE as _wrapper } from "./worker-wrapper.mjs";
+/**
+ * The wrapper source written to `_worker.js`. Imported from the single
+ * canonical `.mjs` file so `src/build.ts` and `bin/cli.mjs` always stay
+ * in sync without any duplication.
+ */
+export const WORKER_WRAPPER_SOURCE = _wrapper;
+/**
+ * Emit a Cloudflare Pages `_worker.js` that wraps the zfb input bundle.
+ *
+ * Output shape (two files in `outdir`):
+ *
+ *   _worker.js       — entry imported by Cloudflare Pages advanced mode
+ *   _zfb_inner.mjs   — the input bundle, copied verbatim
+ *
+ * The wrapper imports the inner bundle via the relative path
+ * `./_zfb_inner.mjs`. Workerd's Module loader resolves relative ESM
+ * imports inside an advanced-mode `_worker.js` directory, so this layout
+ * works without re-bundling.
+ *
+ * Why two files instead of one: re-bundling here would require a second
+ * esbuild pass and would force the adapter to ship its own esbuild
+ * binary slot. The two-file layout keeps the adapter dependency-free at
+ * runtime — it is just `node:fs` glue.
+ */
+export async function emitWorker(input) {
+    const { mkdir, copyFile, writeFile } = await import("node:fs/promises");
+    const { resolve, join } = await import("node:path");
+    const outdir = resolve(input.outdir);
+    const inputBundle = resolve(input.inputBundlePath);
+    await mkdir(outdir, { recursive: true });
+    const innerBundlePath = join(outdir, "_zfb_inner.mjs");
+    await copyFile(inputBundle, innerBundlePath);
+    const workerPath = join(outdir, "_worker.js");
+    await writeFile(workerPath, WORKER_WRAPPER_SOURCE, "utf8");
+    return { workerPath, innerBundlePath };
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,yEAAyE;AACzE,mEAAmE;AAEnE,0EAA0E;AAC1E,sCAAsC;AACtC,OAAO,EAAE,qBAAqB,IAAI,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAW,QAAkB,CAAC;AA+BhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACxE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAEnD,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACvD,MAAM,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IAE7C,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9C,MAAM,SAAS,CAAC,UAAU,EAAE,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAE3D,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cloudflare execution context — minimal projection of the workerd
+ * `ExecutionContext` interface. We do not depend on `@cloudflare/workers-types`
+ * at the type level here because that would force every consumer of this
+ * package to install it; instead we keep a minimal structural shape and
+ * let users widen it via the generic on [`getCloudflareContext`] when
+ * they need richer bindings.
+ */
+export interface CloudflareExecutionContext {
+    /** Extends the lifetime of the request beyond the response. */
+    waitUntil(promise: Promise<unknown>): void;
+    /** Falls through to the static origin on uncaught exceptions. */
+    passThroughOnException(): void;
+}
+/**
+ * Per-request Cloudflare context. `Env` defaults to `unknown` so the
+ * caller can narrow it at the call site (recommended) or leave it open.
+ */
+export interface CloudflareContext<Env = unknown> {
+    /** CF env bindings (secrets, KV, D1, …) wired up via wrangler.toml. */
+    readonly env: Env;
+    /** ExecutionContext for waitUntil / passThroughOnException. */
+    readonly ctx: CloudflareExecutionContext;
+    /** The original Request, useful when handlers want headers / URL. */
+    readonly request: Request;
+}
+/**
+ * Establish a Cloudflare context for the duration of `fn`. Used by the
+ * `_worker.js` wrapper; not normally called by user code.
+ */
+export declare function runWithCloudflareContext<T>(context: CloudflareContext, fn: () => T): T;
+/**
+ * Read the current Cloudflare context. Throws if called outside a
+ * Cloudflare request scope (e.g. from a build-time SSG render). Catch
+ * the error and gate on `prerender = false` if you need a route to work
+ * in both modes.
+ *
+ * The `Env` generic narrows the bindings shape — passing it is
+ * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.
+ */
+export declare function getCloudflareContext<Env = unknown>(): CloudflareContext<Env>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwCA;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,+DAA+D;IAC/D,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3C,iEAAiE;IACjE,sBAAsB,IAAI,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG,GAAG,OAAO;IAC9C,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,0BAA0B,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AA0BD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAG,OAAO,KAAK,iBAAiB,CAAC,GAAG,CAAC,CAU5E"}

package/dist/index.js

@@ -0,0 +1,82 @@
+// `@takazudo/zfb-adapter-cloudflare` — Cloudflare Pages adapter for the
+// zfb framework.
+//
+// This entry (`./`) is the **Workers-runtime** surface. It is safe to
+// bundle into a Cloudflare Worker and does not depend on any Node-only
+// built-ins beyond `node:async_hooks` (which workerd polyfills).
+//
+// Usage in a `prerender = false` route:
+//
+//   import { getCloudflareContext } from "@takazudo/zfb-adapter-cloudflare";
+//
+//   export const prerender = false;
+//   export default async function ApiRoute() {
+//     const { env, ctx } = getCloudflareContext<{ ANTHROPIC_API_KEY: string }>();
+//     // env.ANTHROPIC_API_KEY, ctx.waitUntil(...), etc.
+//   }
+//
+// For Node-only build helpers (e.g. `emitWorker`), import the `./build`
+// sub-entry instead:
+//
+//   import { emitWorker } from "@takazudo/zfb-adapter-cloudflare/build";
+//
+// ## Why AsyncLocalStorage on a globalThis registry
+//
+// Cloudflare Workers can process multiple requests concurrently in the
+// same isolate. A naïve `globalThis.__env = env` write would race across
+// requests. AsyncLocalStorage gives us a per-request scope that survives
+// `await` points without interfering with sibling requests.
+//
+// We register the storage instance on `globalThis` under a stable key
+// (`__zfb_cf_adapter_als__`) so the wrapper at `_worker.js` and the user
+// pages bundled together can share the same instance even when the
+// adapter module ends up duplicated in the final bundle graph (e.g. when
+// the wrapper file is emitted side-by-side with the inner bundle and
+// each pulls in its own copy of this module). Module-instance identity
+// is the property AsyncLocalStorage relies on; the registry pattern is
+// what makes it survive bundler duplication.
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Stable globalThis key the registry pattern uses. */
+const STORAGE_KEY = "__zfb_cf_adapter_als__";
+/**
+ * Acquire (or lazily create) the singleton AsyncLocalStorage instance.
+ *
+ * Stored on `globalThis` under a stable key so the wrapper at
+ * `_worker.js` and the user bundle share state even if the adapter
+ * module ends up duplicated in the final module graph.
+ */
+function getStorage() {
+    const g = globalThis;
+    let als = g[STORAGE_KEY];
+    if (!als) {
+        als = new AsyncLocalStorage();
+        g[STORAGE_KEY] = als;
+    }
+    return als;
+}
+/**
+ * Establish a Cloudflare context for the duration of `fn`. Used by the
+ * `_worker.js` wrapper; not normally called by user code.
+ */
+export function runWithCloudflareContext(context, fn) {
+    return getStorage().run(context, fn);
+}
+/**
+ * Read the current Cloudflare context. Throws if called outside a
+ * Cloudflare request scope (e.g. from a build-time SSG render). Catch
+ * the error and gate on `prerender = false` if you need a route to work
+ * in both modes.
+ *
+ * The `Env` generic narrows the bindings shape — passing it is
+ * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.
+ */
+export function getCloudflareContext() {
+    const c = getStorage().getStore();
+    if (!c) {
+        throw new Error("[zfb-adapter-cloudflare] getCloudflareContext() called outside a Cloudflare request scope. " +
+            "This usually means the route was rendered at build time (SSG) instead of dispatched by " +
+            "the Worker. Add `export const prerender = false;` to the page if it needs Cloudflare bindings.");
+    }
+    return c;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,iBAAiB;AACjB,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,oCAAoC;AACpC,+CAA+C;AAC/C,kFAAkF;AAClF,yDAAyD;AACzD,MAAM;AACN,EAAE;AACF,wEAAwE;AACxE,qBAAqB;AACrB,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,4DAA4D;AAC5D,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,6CAA6C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA8BrD,uDAAuD;AACvD,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAM7C;;;;;;GAMG;AACH,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,UAAuC,CAAC;IAClD,IAAI,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,iBAAiB,EAAqB,CAAC;QACjD,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAI,OAA0B,EAAE,EAAW;IACjF,OAAO,UAAU,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,yFAAyF;YACzF,gGAAgG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,CAA2B,CAAC;AACrC,CAAC"}

package/dist/worker-wrapper.mjs

@@ -0,0 +1,81 @@
+// Single source of truth for the `_worker.js` wrapper string.
+//
+// Kept as a plain `.mjs` module (no TypeScript) so it can be imported from
+// both the typed TypeScript surface (`src/build.ts`) and the dependency-free
+// CLI binary (`bin/cli.mjs`) without needing a TypeScript loader.
+//
+// Do NOT inline this string in any other file. Edit it here and the two
+// consumers automatically see the update.
+
+/** @type {string} */
+export const WORKER_WRAPPER_SOURCE = `// AUTO-GENERATED by @takazudo/zfb-adapter-cloudflare. Do not edit.
+//
+// Cloudflare Pages advanced mode entry. Forwards (request, env, ctx) to
+// the inner zfb worker bundle, exposing env/ctx to user code via
+// AsyncLocalStorage under a stable globalThis key.
+//
+// The same key is read by @takazudo/zfb-adapter-cloudflare's
+// getCloudflareContext() inside the user bundle, so the two ends share
+// state even though they live in separate ESM module instances.
+//
+// CF Pages advanced-mode contract: when _worker.js is present, every
+// request hits the worker — static asset routing is OFF unless the
+// worker explicitly delegates to env.ASSETS. The dispatch order below
+// is deliberately "ASSETS first, inner on 404":
+//
+//   - GET/HEAD requests probe env.ASSETS first. CF Pages' asset server
+//     handles the trailing-slash canonicalisation for SSG output (e.g.
+//     "/docs/foo" → 308 → "/docs/foo/" → dist/docs/foo/index.html), so
+//     prerendered routes get the build-time head-injected HTML
+//     (<link rel="stylesheet">, <script type="module" src="/assets/
+//     islands-…">). If we let the inner Hono router handle them first,
+//     it would dynamic-SSR the page WITHOUT the prod head injection
+//     (which is a build-time post-process, not a runtime concern), and
+//     islands would never hydrate. See zfb#XXX (filed by Wave 10 of
+//     the zudo-doc#1355 zfb-pipeline-gaps epic).
+//   - On 404 from ASSETS, fall through to the inner zfb worker. This is
+//     where genuinely dynamic routes (\`prerender = false\`, e.g.
+//     \`pages/api/*.tsx\`) are served.
+//   - Non-GET/HEAD requests skip ASSETS and go straight to the inner —
+//     CF Pages assets are read-only by definition, and we want POSTs
+//     (\`/api/ai-chat\`, etc.) to reach the SSR handler without a probe
+//     that would always 405 / 404.
+import { AsyncLocalStorage } from "node:async_hooks";
+import inner from "./_zfb_inner.mjs";
+
+const STORAGE_KEY = "__zfb_cf_adapter_als__";
+
+function getStorage() {
+  const g = globalThis;
+  let als = g[STORAGE_KEY];
+  if (!als) {
+    als = new AsyncLocalStorage();
+    g[STORAGE_KEY] = als;
+  }
+  return als;
+}
+
+function canDelegateToAssets(env) {
+  return Boolean(env && env.ASSETS && typeof env.ASSETS.fetch === "function");
+}
+
+function isAssetProbeMethod(method) {
+  // Only safe, side-effect-free methods probe the asset server. POST/
+  // PUT/PATCH/DELETE go straight to the inner SSR worker.
+  return method === "GET" || method === "HEAD";
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    if (isAssetProbeMethod(request.method) && canDelegateToAssets(env)) {
+      const assetResponse = await env.ASSETS.fetch(request);
+      if (assetResponse.status !== 404) {
+        return assetResponse;
+      }
+      // Fall through to the inner worker for genuinely dynamic routes.
+    }
+    const store = { env, ctx, request };
+    return getStorage().run(store, () => inner.fetch(request));
+  },
+};
+`;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@takazudo/zfb-adapter-cloudflare",
+  "version": "0.1.0-next.2",
+  "private": false,
+  "type": "module",
+  "description": "Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary. Cloudflare Pages adapter.",
+  "keywords": [
+    "zfb",
+    "zfb-adapter",
+    "cloudflare",
+    "cloudflare-pages",
+    "cloudflare-workers",
+    "ssg",
+    "static-site-generator",
+    "adapter"
+  ],
+  "license": "MIT",
+  "author": "Takeshi Takatsudo <takazudo@gmail.com> (https://github.com/Takazudo)",
+  "homepage": "https://takazudomodular.com/pj/zudo-front-builder/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Takazudo/zudo-front-builder.git",
+    "directory": "packages/zfb-adapter-cloudflare"
+  },
+  "bugs": {
+    "url": "https://github.com/Takazudo/zudo-front-builder/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    }
+  },
+  "bin": {
+    "zfb-adapter-cloudflare": "./bin/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src/worker-wrapper.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsc && cp src/worker-wrapper.mjs dist/worker-wrapper.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/worker-wrapper.mjs

@@ -0,0 +1,81 @@
+// Single source of truth for the `_worker.js` wrapper string.
+//
+// Kept as a plain `.mjs` module (no TypeScript) so it can be imported from
+// both the typed TypeScript surface (`src/build.ts`) and the dependency-free
+// CLI binary (`bin/cli.mjs`) without needing a TypeScript loader.
+//
+// Do NOT inline this string in any other file. Edit it here and the two
+// consumers automatically see the update.
+
+/** @type {string} */
+export const WORKER_WRAPPER_SOURCE = `// AUTO-GENERATED by @takazudo/zfb-adapter-cloudflare. Do not edit.
+//
+// Cloudflare Pages advanced mode entry. Forwards (request, env, ctx) to
+// the inner zfb worker bundle, exposing env/ctx to user code via
+// AsyncLocalStorage under a stable globalThis key.
+//
+// The same key is read by @takazudo/zfb-adapter-cloudflare's
+// getCloudflareContext() inside the user bundle, so the two ends share
+// state even though they live in separate ESM module instances.
+//
+// CF Pages advanced-mode contract: when _worker.js is present, every
+// request hits the worker — static asset routing is OFF unless the
+// worker explicitly delegates to env.ASSETS. The dispatch order below
+// is deliberately "ASSETS first, inner on 404":
+//
+//   - GET/HEAD requests probe env.ASSETS first. CF Pages' asset server
+//     handles the trailing-slash canonicalisation for SSG output (e.g.
+//     "/docs/foo" → 308 → "/docs/foo/" → dist/docs/foo/index.html), so
+//     prerendered routes get the build-time head-injected HTML
+//     (<link rel="stylesheet">, <script type="module" src="/assets/
+//     islands-…">). If we let the inner Hono router handle them first,
+//     it would dynamic-SSR the page WITHOUT the prod head injection
+//     (which is a build-time post-process, not a runtime concern), and
+//     islands would never hydrate. See zfb#XXX (filed by Wave 10 of
+//     the zudo-doc#1355 zfb-pipeline-gaps epic).
+//   - On 404 from ASSETS, fall through to the inner zfb worker. This is
+//     where genuinely dynamic routes (\`prerender = false\`, e.g.
+//     \`pages/api/*.tsx\`) are served.
+//   - Non-GET/HEAD requests skip ASSETS and go straight to the inner —
+//     CF Pages assets are read-only by definition, and we want POSTs
+//     (\`/api/ai-chat\`, etc.) to reach the SSR handler without a probe
+//     that would always 405 / 404.
+import { AsyncLocalStorage } from "node:async_hooks";
+import inner from "./_zfb_inner.mjs";
+
+const STORAGE_KEY = "__zfb_cf_adapter_als__";
+
+function getStorage() {
+  const g = globalThis;
+  let als = g[STORAGE_KEY];
+  if (!als) {
+    als = new AsyncLocalStorage();
+    g[STORAGE_KEY] = als;
+  }
+  return als;
+}
+
+function canDelegateToAssets(env) {
+  return Boolean(env && env.ASSETS && typeof env.ASSETS.fetch === "function");
+}
+
+function isAssetProbeMethod(method) {
+  // Only safe, side-effect-free methods probe the asset server. POST/
+  // PUT/PATCH/DELETE go straight to the inner SSR worker.
+  return method === "GET" || method === "HEAD";
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    if (isAssetProbeMethod(request.method) && canDelegateToAssets(env)) {
+      const assetResponse = await env.ASSETS.fetch(request);
+      if (assetResponse.status !== 404) {
+        return assetResponse;
+      }
+      // Fall through to the inner worker for genuinely dynamic routes.
+    }
+    const store = { env, ctx, request };
+    return getStorage().run(store, () => inner.fetch(request));
+  },
+};
+`;