@octanejs/adapter-cloudflare 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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,79 @@
+# `@octanejs/adapter-cloudflare`
+
+Deploy an Octane full-stack build to Cloudflare Workers with Workers Static
+Assets. The adapter keeps the existing `dist/client` and `dist/server` layout
+and adds a module Worker entry at `dist/server/worker.js`.
+
+```bash
+pnpm add @octanejs/adapter-cloudflare
+pnpm add -D wrangler
+```
+
+## Configure Octane
+
+```ts
+import { cloudflare } from '@octanejs/adapter-cloudflare';
+import { defineConfig, RenderRoute } from '@octanejs/vite-plugin';
+
+export default defineConfig({
+	adapter: cloudflare(),
+	router: {
+		routes: [new RenderRoute({ path: '/*path', entry: '/src/App.tsrx' })],
+	},
+});
+```
+
+The same adapter contract is supported by `@octanejs/rsbuild-plugin`.
+
+## Configure Wrangler
+
+Keep `wrangler.jsonc` in your app as the source of truth so bindings, routes,
+secrets, environments, placement, and observability remain under your control:
+
+```jsonc
+{
+	"$schema": "./node_modules/wrangler/config-schema.json",
+	"name": "my-octane-app",
+	"main": "./dist/server/worker.js",
+	"compatibility_date": "2026-07-14",
+	"compatibility_flags": ["nodejs_compat"],
+	"assets": {
+		"directory": "./dist/client",
+		"binding": "ASSETS",
+	},
+}
+```
+
+`nodejs_compat` is currently required for the synchronous SHA-256 and
+`AsyncLocalStorage` primitives used by Octane server functions and request-local
+fetch handling. Use a current compatibility date when creating a new app.
+
+Build first, then run or deploy the exact production output:
+
+```bash
+pnpm vite build
+pnpm wrangler dev
+pnpm wrangler deploy
+```
+
+Cloudflare's default asset-first routing is the intended setup: exact files in
+`dist/client` are served without invoking the Worker, and every miss reaches
+Octane SSR. Leave `assets.not_found_handling` unset (the default `"none"`) or
+set it explicitly to `"none"`: both `"single-page-application"` and
+`"404-page"` can prevent browser-navigation misses from reaching SSR. Leave
+`run_worker_first` unset/`false` unless every asset request intentionally needs
+Worker logic.
+
+The generated Worker forwards Cloudflare's request-scoped `{ env, ctx }` as
+`context.platform` to middleware and `ServerRoute` handlers:
+
+```ts
+import type { CloudflarePlatform } from '@octanejs/adapter-cloudflare';
+
+const platform = context.platform as CloudflarePlatform<Env>;
+await platform.env.MY_KV.get('key');
+platform.ctx.waitUntil(writeAnalytics());
+```
+
+Streaming SSR remains a Web `ReadableStream` from Octane through the Worker;
+the adapter does not buffer or translate the response body.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@octanejs/adapter-cloudflare",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Cloudflare Workers adapter for Octane apps",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/adapter-cloudflare"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "worker": "./src/worker.js",
+      "browser": "./src/worker.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@octanejs/app-core": "0.0.7"
+  },
+  "devDependencies": {
+    "@rsbuild/core": "^2.1.5",
+    "@types/node": "^24.3.0",
+    "miniflare": "4.20260714.0",
+    "vite": "^8.0.16",
+    "@octanejs/app-core": "0.0.7",
+    "@octanejs/rsbuild-plugin": "0.1.6",
+    "@octanejs/vite-plugin": "0.1.11",
+    "octane": "0.1.11"
+  }
+}

package/src/adapt.js

@@ -0,0 +1,86 @@
+// @ts-check
+/**
+ * Cloudflare module Worker emitter.
+ *
+ * Octane's web-worker server build exports `createWebWorkerHandler()` and is
+ * already self-contained. This final build step embeds the transformed HTML
+ * template (and Rsbuild's late client asset map, when present) into a tiny
+ * module Worker entry. Cloudflare serves `dist/client` asset-first; only misses
+ * reach this handler, so the client index remains private under dist/server.
+ */
+
+/** @import { AdaptContext } from '@octanejs/app-core' */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CLIENT_ASSET_MAP = 'octane-client-assets.json';
+const WORKER_ENTRY = 'worker.js';
+const GENERATED_WORKER_HEADER = '// Auto-generated by @octanejs/adapter-cloudflare';
+
+/**
+ * @param {string} htmlTemplate
+ * @param {Record<string, unknown> | undefined} clientAssets
+ * @returns {string}
+ */
+function generateWorkerSource(htmlTemplate, clientAssets) {
+	const options = { htmlTemplate, ...(clientAssets === undefined ? null : { clientAssets }) };
+	return `${GENERATED_WORKER_HEADER} — do not edit.
+import { createWebWorkerHandler } from './entry.js';
+
+let handler;
+
+export default {
+	async fetch(request, env, ctx) {
+		try {
+			handler ??= createWebWorkerHandler(${JSON.stringify(options, null, '\t')});
+			return await handler(request, { env, ctx });
+		} catch (error) {
+			console.error('[octane] Cloudflare Worker handler error:', error);
+			return new Response('Internal Server Error', { status: 500 });
+		}
+	},
+};
+`;
+}
+
+/**
+ * @param {AdaptContext} ctx
+ * @returns {Promise<void>}
+ */
+export async function emitCloudflareWorker(ctx) {
+	const { clientDir, serverDir } = ctx;
+	const log = ctx.log ?? ((/** @type {string} */ message) => console.log(message));
+	const serverEntry = join(serverDir, 'entry.js');
+	const htmlTemplate = join(serverDir, 'index.html');
+
+	if (!existsSync(clientDir)) {
+		throw new Error(
+			`[@octanejs/adapter-cloudflare] Client build output not found at ${clientDir}.`,
+		);
+	}
+	if (!existsSync(serverEntry)) {
+		throw new Error(`[@octanejs/adapter-cloudflare] Server entry not found at ${serverEntry}.`);
+	}
+	if (!existsSync(htmlTemplate)) {
+		throw new Error(
+			`[@octanejs/adapter-cloudflare] Server HTML template not found at ${htmlTemplate}.`,
+		);
+	}
+
+	const clientAssetMap = join(serverDir, CLIENT_ASSET_MAP);
+	const clientAssets = existsSync(clientAssetMap)
+		? JSON.parse(readFileSync(clientAssetMap, 'utf-8'))
+		: undefined;
+	const output = join(serverDir, WORKER_ENTRY);
+	if (existsSync(output) && !readFileSync(output, 'utf-8').startsWith(GENERATED_WORKER_HEADER)) {
+		throw new Error(
+			`[@octanejs/adapter-cloudflare] Refusing to replace ${output}: the server build already emitted worker.js. Configure asynchronous server chunks under a subdirectory.`,
+		);
+	}
+	writeFileSync(output, generateWorkerSource(readFileSync(htmlTemplate, 'utf-8'), clientAssets));
+
+	log(
+		`[@octanejs/adapter-cloudflare] Worker entry written to ${join(ctx.outDir, 'server', WORKER_ENTRY)}`,
+	);
+}

package/src/index.js

@@ -0,0 +1,35 @@
+// @ts-check
+/**
+ * @octanejs/adapter-cloudflare — Cloudflare Workers adapter for Octane apps.
+ *
+ * The production integrations see `serverTarget: 'webworker'` and emit a
+ * template-free Worker bundle. After both bundles exist, adapt() embeds the
+ * built HTML template in `dist/server/worker.js`, the module Worker entry that
+ * a user-owned wrangler.jsonc deploys beside `dist/client` static assets.
+ */
+
+/** @import { AdaptContext, OctaneAdapter } from '@octanejs/app-core' */
+
+import { emitCloudflareWorker } from './adapt.js';
+import { runtime } from './runtime.js';
+
+/**
+ * Emit the Cloudflare module Worker entry after an Octane production build.
+ * @param {AdaptContext} ctx
+ * @returns {Promise<void>}
+ */
+export async function adapt(ctx) {
+	await emitCloudflareWorker(ctx);
+}
+
+/**
+ * @returns {OctaneAdapter}
+ */
+export function cloudflare() {
+	return {
+		name: 'cloudflare',
+		serverTarget: 'webworker',
+		runtime,
+		adapt,
+	};
+}

package/src/runtime.js

@@ -0,0 +1,21 @@
+// @ts-check
+/** Cloudflare-compatible primitives consumed by app-core's production handler. */
+
+/** @import { OctaneAdapter } from '@octanejs/app-core' */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+
+/** @type {NonNullable<OctaneAdapter['runtime']>} */
+export const runtime = {
+	hash(value) {
+		return createHash('sha256').update(value).digest('hex').slice(0, 8);
+	},
+	createAsyncContext() {
+		const storage = new AsyncLocalStorage();
+		return {
+			run: (store, callback) => storage.run(store, callback),
+			getStore: () => storage.getStore(),
+		};
+	},
+};

package/src/worker.js

@@ -0,0 +1,29 @@
+// @ts-check
+/**
+ * Runtime-only facade selected while bundling for a browser/Worker target.
+ * Build-time filesystem emission stays in the default Node export.
+ */
+
+/** @import { AdaptContext, OctaneAdapter } from '@octanejs/app-core' */
+
+import { runtime } from './runtime.js';
+
+/**
+ * This facade is bundled into the deployed Worker; adaptation only runs in the
+ * parent Node build, so reaching it here indicates a build integration bug.
+ * @param {AdaptContext} _ctx
+ * @returns {Promise<void>}
+ */
+export async function adapt(_ctx) {
+	throw new Error('[octane] Cloudflare adapt() is only available during the Node build.');
+}
+
+/** @returns {OctaneAdapter} */
+export function cloudflare() {
+	return {
+		name: 'cloudflare',
+		serverTarget: 'webworker',
+		runtime,
+		adapt,
+	};
+}

package/types/index.d.ts

@@ -0,0 +1,23 @@
+import type { AdaptContext, OctaneAdapter } from '@octanejs/app-core';
+
+/** The minimal execution-context surface used by the adapter. */
+export interface CloudflareExecutionContext {
+	waitUntil(promise: Promise<unknown>): void;
+	passThroughOnException(): void;
+	props?: unknown;
+}
+
+/** Available as `context.platform` in Octane middleware and ServerRoutes. */
+export interface CloudflarePlatform<
+	Env = Record<string, unknown>,
+	ExecutionContext extends CloudflareExecutionContext = CloudflareExecutionContext,
+> {
+	env: Env;
+	ctx: ExecutionContext;
+}
+
+/** Select Cloudflare's Worker build target and emit dist/server/worker.js. */
+export function cloudflare(): OctaneAdapter;
+
+/** Emit dist/server/worker.js from completed Octane client/server bundles. */
+export function adapt(ctx: AdaptContext): Promise<void>;