| 1 | # `@alchemy.run/frontend-frameworks/octane` |
| 2 | |
| 3 | Wrangler-free [OctaneJS](https://octanejs.dev) integration implementing the |
| 4 | framework-core `Framework` service, with the deploy target passed as a value |
| 5 | (Cloudflare Workers built in at `./cloudflare`). |
| 6 | |
| 7 | Keep the native `octane()` plugin in `vite.config.ts` and application routes |
| 8 | in `octane.config.ts`. Cloudflare builds no longer require |
| 9 | `@octanejs/adapter-cloudflare` or an `adapter` declaration: |
| 10 | |
| 11 | ```diff |
| 12 | -import { cloudflare } from "@octanejs/adapter-cloudflare"; |
| 13 | import { defineConfig, RenderRoute } from "@octanejs/vite-plugin"; |
| 14 | |
| 15 | export default defineConfig({ |
| 16 | - adapter: cloudflare(), |
| 17 | router: { |
| 18 | routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })], |
| 19 | }, |
| 20 | }); |
| 21 | ``` |
| 22 | |
| 23 | Existing Cloudflare adapter declarations remain supported. The native config |
| 24 | is never rewritten, and other native Vite plugins remain active. |
| 25 | |
| 26 | Alchemy keeps Octane's client compilation, hydration, and asset metadata, |
| 27 | but replaces its automatic server build with a Worker-targeted Vite build. |
| 28 | Octane's public server-manifest generator supplies the routes and runtime; |
| 29 | Alchemy generates the small `fetch(request, env, ctx)` entry and embeds the |
| 30 | HTML template. The existing source provider isolates builds in a child process |
| 31 | and collects the output: |
| 32 | |
| 33 | - `dist/client` — static assets, served asset-first |
| 34 | - `dist/server/worker.js` — the Worker entry; custom Octane `build.outDir` |
| 35 | values are also supported |
| 36 | |
| 37 | The Worker needs `nodejs_compat` for Octane's hashing and asynchronous request |
| 38 | context. No Wrangler configuration is required. The build integration uses |
| 39 | the installed Octane Vite plugin's client-asset helper and production config |
| 40 | facade alongside its public code-generation API; compatibility is covered by |
| 41 | a real adapter-free build regression. |
| 42 | |
| 43 | `dev` runs Octane's own Vite dev server (the plugin's dev SSR middleware — |
| 44 | rendering, server routes, and RPC in-process with full HMR). |
| 45 | |
| 46 | ## Usage |
| 47 | |
| 48 | ```ts |
| 49 | // e2e.config.ts (the fixture harness) |
| 50 | export default Options.make({ |
| 51 | framework: "@alchemy.run/frontend-frameworks/octane", |
| 52 | target: { |
| 53 | cloudflare: { |
| 54 | worker: { compatibilityDate: "2026-03-10", compatibilityFlags: ["nodejs_compat"] }, |
| 55 | }, |
| 56 | }, |
| 57 | }); |
| 58 | ``` |
| 59 | |
| 60 | On the alchemy side, `Cloudflare.Website.Octane` uses the |
| 61 | `@alchemy.run/frontend-frameworks/octane/source` subpath (the alchemy Worker source-provider |
| 62 | contract). |
| 63 | |
| 64 | ## Limitations |
| 65 | |
| 66 | - **Dev bindings**: Octane's dev middleware supplies no request-scoped |
| 67 | `context.platform` (upstream limitation), so Cloudflare bindings are only |
| 68 | observable in production builds and previews, not in `dev`. |
| 69 | - **SPA apps**: a client-only Octane app (no `octane.config.ts` routes) is a |
| 70 | plain Vite SPA — deploy it through the plain Vite integration |
| 71 | (`Cloudflare.Website.Vite`), where the `octane()` compiler plugin composes |
| 72 | with the injected Cloudflare Vite plugin. |