@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 188 lines 5.17 KB
Raw
1 ---
2 title: Octane
3 description: Deploy an OctaneJS app to Fly with Fly.Website.Octane — SSR on a Machine, client assets baked into the image, and Octane's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 14
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Fly.Website.Octane` deploys an [OctaneJS](https://octanejs.dev)
13 fullstack app to Fly. Octane wraps Vite, so the resource is
14 deliberately thin: it runs your project's own `vite build` — Octane's
15 plugin builds the client bundle and the self-contained SSR server
16 bundle, and the Node deploy target's finishing pass wraps its fetch
17 handler as a Node HTTP program. The server runs on a Machine
18 (`Fly.Service` on a `Fly.App`, plus a shared IPv4 so
19 `https://{app}.fly.dev` answers); client assets are baked into the
20 image. No Dockerfile, no build command to run.
21
22 ## Install
23
24 The build integration is not bundled with alchemy. Install
25 `@alchemy.run/frontend-frameworks`; the resource loads the package's
26 `/octane` and `/octane/node` exports from your project at deploy
27 time. It is only used at build time, so a dev dependency is enough:
28
29 <PackageManagers dev={devDeps} />
30
31 ## Configure Octane
32
33 Keep native compiler and route settings in `octane.config.ts`, without
34 an adapter:
35
36 ```typescript
37 // octane.config.ts
38 import { defineConfig, RenderRoute } from "@octanejs/vite-plugin";
39
40 export default defineConfig({
41 router: {
42 routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })],
43 },
44 });
45 ```
46
47 `Fly.Website.Octane` selects hosting and automatically wraps Octane's
48 default native Node output as an HTTP server. The legacy Node marker
49 adapter remains optional for existing projects.
50
51 Vite plugins like Tailwind go in `vite.config.ts` next to it,
52 alongside the Octane plugin:
53
54 ```typescript
55 // vite.config.ts
56 import { octane } from "@octanejs/vite-plugin";
57 import tailwindcss from "@tailwindcss/vite";
58 import { defineConfig } from "vite";
59
60 export default defineConfig({
61 plugins: [octane(), tailwindcss()],
62 });
63 ```
64
65 ## Declare the Website
66
67 Declare the site as a module-level const (rather than inline in the
68 Stack):
69
70 ```typescript
71 // alchemy.run.ts
72 import * as Fly from "@alchemy.run/fly";
73
74 export const Website = Fly.Website.Octane("Website");
75 ```
76
77 Omit `app` and Alchemy creates a `Fly.App` under the site's
78 namespace. Pass an existing App to put the site on it:
79
80 ```typescript
81 export const Site = Fly.App("Site");
82
83 export const Website = Fly.Website.Octane("Website", {
84 app: Site,
85 });
86 ```
87
88 ## Add it to the Stack
89
90 Yield the site from your Stack and return its URL:
91
92 ```typescript
93 // alchemy.run.ts
94 import * as Alchemy from "alchemy";
95 import * as Effect from "effect/Effect";
96
97 export default Alchemy.Stack(
98 "MyOctaneSite",
99 {
100 providers: Fly.providers(),
101 state: Alchemy.localState(),
102 },
103 Effect.gen(function* () {
104 const site = yield* Website;
105 return { url: site.url };
106 }),
107 );
108 ```
109
110 On deploy, `url` is `https://{app}.fly.dev`. The resolved site also
111 exposes `app`, `service`, `ip`, and `certificate` (all `undefined`
112 under `alchemy dev`).
113
114 ## Add environment variables
115
116 Process environment is configured under `env` — plain strings, or
117 `Redacted` values. They are copied onto `process.env` before the
118 build and onto the Machine at deploy time:
119
120 ```diff lang="typescript"
121 // alchemy.run.ts
122 export const Website = Fly.Website.Octane("Website", {
123 + env: {
124 + GREETING: "Hello from alchemy",
125 + API_BASE: "https://api.example.com",
126 + },
127 });
128 ```
129
130 The same values are injected into the dev server's process
131 environment under `alchemy dev`, so server code reads them in both
132 modes.
133
134 ## Read the environment in server code
135
136 Octane's server runs in Node on the Machine, so middleware and
137 `ServerRoute` handlers read the environment from `process.env`:
138
139 ```typescript
140 // octane.config.ts
141 new ServerRoute({
142 path: "/api/greeting",
143 methods: ["GET"],
144 handler: async () => {
145 return Response.json({ greeting: process.env.GREETING ?? "hello" });
146 },
147 });
148 ```
149
150 ## Asset routing
151
152 Octane's intended setup is asset-first with SSR on miss: exact files
153 in `dist/client` are served by the Node process without invoking the
154 Octane handler, and every miss streams from Octane SSR. That is the
155 default — there is nothing to configure. `GET /health` answers for
156 the platform health check.
157
158 ## Local dev
159
160 ```sh
161 bun alchemy dev
162 ```
163
164 `alchemy dev` runs Octane's own Vite dev server — the plugin's
165 in-process SSR middleware serves rendering, server routes, and RPC
166 with full HMR. `site.url` is the local address and no Fly resources
167 are created (`app`, `service`, `ip`, and `certificate` are
168 `undefined`). Wrap the site in `Alchemy.remote()` to deploy the real
169 infrastructure even during dev.
170
171 ## Custom domain
172
173 ```typescript
174 const site = yield* Fly.Website.Octane("Web", {
175 domain: "app.example.com",
176 });
177 ```
178
179 Alchemy requests ACME (`Fly.Certificate`) on the App and `url`
180 becomes `https://{domain}`. Point existing DNS at the App — the
181 Website does not create DNS records. See
182 [IPs & certificates](/fly/networking).
183
184 ## Where next
185
186 - [`Fly.Website.Octane` reference](/providers/fly/website/octane)
187 - [Apps](/fly/compute/apps) and [Services](/fly/compute/services)
188 - [IPs & certificates](/fly/networking)