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

main
mdx 163 lines 4.46 KB
Raw
1 ---
2 title: Octane
3 description: Deploy an OctaneJS app to AWS with AWS.Website.Octane — SSR on a Lambda Web Function, assets on S3 + CloudFront, 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 `AWS.Website.Octane` deploys an [OctaneJS](https://octanejs.dev)
13 fullstack app to AWS. 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 deploy target's finishing pass wraps its fetch handler
17 in a Node server. The server deploys on a
18 [Lambda Web Function](/aws/compute/web-functions); `dist/client` is
19 served from a private S3 bucket
20 through CloudFront. No CloudFormation, 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 time.
27 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 `AWS.Website.Octane` selects hosting and automatically wraps Octane's
48 default native Node output in a Node server. The legacy AWS
49 marker adapter remains optional for existing projects.
50
51 ## Declare the Website
52
53 Declare the site as a module-level const (rather than inline in the
54 Stack):
55
56 ```typescript
57 // alchemy.run.ts
58 import * as AWS from "@alchemy.run/aws";
59
60 export const Website = AWS.Website.Octane("Website");
61 ```
62
63 ## Add it to the Stack
64
65 Yield the site from your Stack and return its URL:
66
67 ```typescript
68 // alchemy.run.ts
69 import * as Alchemy from "alchemy";
70 import * as Effect from "effect/Effect";
71
72 export default Alchemy.Stack(
73 "MyOctaneSite",
74 {
75 providers: AWS.providers(),
76 state: AWS.state(),
77 },
78 Effect.gen(function* () {
79 const site = yield* Website;
80 return { url: site.url };
81 }),
82 );
83 ```
84
85 ## Add environment variables
86
87 The server function's environment is configured under `env` — plain
88 values, or outputs from other resources in the Stack:
89
90 ```diff lang="typescript"
91 // alchemy.run.ts
92 export const Website = AWS.Website.Octane("Website", {
93 + env: {
94 + GREETING: "Hello from alchemy",
95 + API_BASE: api.url,
96 + },
97 });
98 ```
99
100 The values are set on the server at deploy time and injected into the
101 dev server's process environment under `alchemy dev`, so server code
102 reads the same values in both modes.
103
104 ## Read the environment in server code
105
106 Octane's server is a plain Node server, so middleware and
107 `ServerRoute` handlers read the environment from `process.env`:
108
109 ```typescript
110 // octane.config.ts
111 new ServerRoute({
112 path: "/api/greeting",
113 methods: ["GET"],
114 handler: async () => {
115 return Response.json({ greeting: process.env.GREETING ?? "hello" });
116 },
117 });
118 ```
119
120 ## Asset routing
121
122 Octane's intended setup is asset-first with SSR on miss: exact files
123 in `dist/client` serve from S3 via the CloudFront edge router without
124 invoking the server, and every miss streams from Octane SSR on the
125 server. That is the default — there is nothing to configure.
126
127 ## Run on a Lambda Function
128
129 Web Functions run in a subset of Regions. Elsewhere, set
130 `server: "function"`: the app builds with the `/octane/aws` deploy target
131 and runs on a Lambda Function behind a streaming Function URL, tuned with
132 `memorySize`, `architecture`, and `runtime`:
133
134 ```diff lang="typescript"
135 // alchemy.run.ts
136 export const Website = AWS.Website.Octane("Website", {
137 + server: "function",
138 + memorySize: 2048,
139 });
140 ```
141
142 ## Local dev
143
144 ```sh
145 bun alchemy dev
146 ```
147
148 `alchemy dev` runs Octane's own Vite dev server — the plugin's
149 in-process SSR middleware serves rendering, server routes, and RPC
150 with full HMR. `site.url` is the local address and no AWS resources
151 are created. Wrap the site in `Alchemy.remote()` to deploy the real
152 infrastructure even during dev.
153
154 ## Custom domain
155
156 ```typescript
157 const site = yield* AWS.Website.Octane("Web", {
158 domain: { name: "app.example.com" },
159 });
160 ```
161
162 The hosted zone is inferred from the hostname. Pass `hostedZoneId` to
163 pin it when several zones could match.