@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 220 lines 6.87 KB
Raw
1 ---
2 title: Octane
3 description: Deploy an OctaneJS fullstack app to Cloudflare Workers with Cloudflare.Website.Octane — native Octane and Vite configuration, no hosting adapter or Wrangler file required.
4 sidebar:
5 order: 13
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Cloudflare.Website.Octane` builds and deploys an [OctaneJS](https://octanejs.dev)
13 fullstack app as a Cloudflare Worker. Alchemy preserves Octane's native
14 compiler and client build, builds the server for Workers, and generates
15 the Worker entry. No hosting adapter, Wrangler file, or separate build
16 command is required.
17
18 Your `vite.config.ts` and `octane.config.ts` load without being rewritten.
19 Keep the native `octane()` plugin, Tailwind, other Vite plugins, and your
20 application routes and callbacks. By default, `dist/server/worker.js`
21 deploys as the Worker script and `dist/client` deploys as static assets;
22 custom Octane `build.outDir` values are also supported.
23
24 ## Install
25
26 Keep `octane` and `@octanejs/vite-plugin` in your existing Octane project.
27 Add `@alchemy.run/frontend-frameworks` as a dev dependency; Alchemy loads
28 its Octane integration at deploy time. `@octanejs/adapter-cloudflare` is
29 optional:
30
31 <PackageManagers dev={devDeps} />
32
33 ## Configure Octane
34
35 Define application routes in `octane.config.ts`.
36 `Cloudflare.Website.Octane` selects the Worker build, so this file does
37 not need an `adapter` declaration:
38
39 ```typescript
40 // octane.config.ts
41 import { defineConfig, RenderRoute } from "@octanejs/vite-plugin";
42
43 export default defineConfig({
44 router: {
45 routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })],
46 },
47 });
48 ```
49
50 ## Existing Cloudflare adapter configurations
51
52 Existing `adapter: cloudflare()` declarations remain supported; migration
53 is optional. To remove the adapter, delete its import and declaration:
54
55 ```diff lang="typescript"
56 // octane.config.ts
57 -import { cloudflare } from "@octanejs/adapter-cloudflare";
58 import { defineConfig, RenderRoute } from "@octanejs/vite-plugin";
59
60 export default defineConfig({
61 - adapter: cloudflare(),
62 router: {
63 routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })],
64 },
65 });
66 ```
67
68 You can then uninstall `@octanejs/adapter-cloudflare` if nothing else in
69 your project uses it. Keep `octane()`, Tailwind, and other native plugins
70 in `vite.config.ts`. An adapter for a different hosting target is rejected
71 rather than silently overridden.
72
73 ## Declare the Website
74
75 Declare the site as a module-level const (rather than inline in the
76 Stack) and derive the typed shape of its bindings from it:
77
78 ```typescript
79 // alchemy.run.ts
80 import * as Cloudflare from "@alchemy.run/cloudflare";
81
82 export const Website = Cloudflare.Website.Octane("Website");
83
84 export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;
85 ```
86
87 `WebsiteEnv` is the typed shape of the Worker's bindings, derived
88 from the class — you'll import it into your Octane code in
89 [Read bindings in server code](#read-bindings-in-server-code).
90
91 ## Add it to the Stack
92
93 Yield the class from your Stack and return its URL:
94
95 ```typescript
96 // alchemy.run.ts
97 import * as Alchemy from "alchemy";
98 import * as Effect from "effect/Effect";
99
100 export default Alchemy.Stack(
101 "MyOctaneSite",
102 {
103 providers: Cloudflare.providers(),
104 state: Cloudflare.state(),
105 },
106 Effect.gen(function* () {
107 const site = yield* Website;
108 return { url: site.url };
109 }),
110 );
111 ```
112
113 Octane's server runtime uses synchronous SHA-256 and
114 `AsyncLocalStorage`, which need the `nodejs_compat` compatibility flag —
115 it is enabled by default for every Worker, so there is nothing to pass.
116
117 See
118 [examples/cloudflare-octane](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-octane)
119 for the checked-in example.
120
121 ## Add bindings
122
123 The resource returns a plain `Worker`, so `env` accepts the full binding
124 vocabulary — KV namespaces, R2 buckets, secrets:
125
126 ```diff lang="typescript"
127 // alchemy.run.ts
128 +import * as Config from "effect/Config";
129
130 +export const Cache = Cloudflare.KV.Namespace("Cache");
131
132 export const Website = Cloudflare.Website.Octane("Website", {
133 + env: {
134 + CACHE: Cache,
135 + API_KEY: Config.Redacted("API_KEY"),
136 + },
137 });
138 ```
139
140 `Cache` is a description, not a deploy — Alchemy provisions the real
141 namespace because the Website binds it. `Config.Redacted` reads
142 `API_KEY` from your environment at deploy time and binds it as a
143 Worker secret — see [Secrets & env](/cloudflare/security/secrets-env).
144
145 ## Read bindings in server code
146
147 Octane middleware and `ServerRoute` handlers read bindings through
148 `context.platform`, which the generated Worker entry supplies as the Cloudflare
149 `{ env, ctx }` pair. Type it with the inferred env type — `env` and
150 `ctx` are optional because Octane's dev server supplies no platform
151 (see [Local dev](#local-dev)):
152
153 ```typescript
154 // octane.config.ts
155 import type { WebsiteEnv } from "./alchemy.run.ts";
156
157 interface Platform {
158 readonly env?: WebsiteEnv;
159 readonly ctx?: { waitUntil(promise: Promise<unknown>): void };
160 }
161
162 new ServerRoute({
163 path: "/api/visits",
164 methods: ["GET"],
165 handler: async (context) => {
166 const platform = context.platform as Platform | undefined;
167 const cache = platform?.env?.CACHE;
168 if (cache === undefined) {
169 return Response.json({ visits: null, dev: true });
170 }
171 const visits = Number((await cache.get("visits")) ?? "0") + 1;
172 platform?.ctx?.waitUntil(cache.put("visits", String(visits)));
173 return Response.json({ visits });
174 },
175 });
176 ```
177
178 `platform.env.CACHE` is typed as a KV namespace and `.API_KEY` as a
179 string — renaming a binding in `alchemy.run.ts` is a type error in
180 your handlers.
181
182 ## Asset routing
183
184 Octane's intended setup is asset-first with SSR on miss: exact files in
185 `dist/client` serve without invoking the Worker, and every miss reaches
186 Octane SSR. That is the default — leave `assets.notFoundHandling` unset.
187 Both `"single-page-application"` and `"404-page"` would stop
188 browser-navigation misses from reaching SSR.
189
190 ## Octane SPAs use `Vite` instead
191
192 A client-only Octane app (no `octane.config.ts` routes) is a plain Vite
193 SPA — the `octane()` compiler plugin composes with the Cloudflare Vite
194 plugin, so deploy it with
195 [`Cloudflare.Website.Vite`](/cloudflare/frontend/vite):
196
197 ```typescript
198 export const OctaneApp = Cloudflare.Website.Vite("Octane", {
199 assets: {
200 notFoundHandling: "single-page-application",
201 },
202 });
203 ```
204
205 ## Local dev
206
207 ```sh
208 bun alchemy dev
209 ```
210
211 `alchemy dev` runs Octane's own Vite dev server — the plugin's
212 in-process SSR middleware serves rendering, server routes, and RPC with
213 full HMR.
214
215 One limitation, inherited from Octane itself: the dev middleware
216 supplies no request-scoped `context.platform`, so bindings are not
217 observable from dev-mode app code — write handlers to tolerate an
218 `undefined` platform, or pipe the site through `Alchemy.remote()` to
219 deploy the real Worker during dev. Bindings are fully live in deployed
220 Workers and previews.