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

main
mdx 185 lines 4.98 KB
Raw
1 ---
2 title: Waku
3 description: Deploy a Waku app to AWS with AWS.Website.Waku — RSC server on a Lambda Web Function, SSG pages and assets on S3 + CloudFront, and Waku's own dev server under alchemy dev.
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 `AWS.Website.Waku` deploys a [Waku](https://waku.gg) app (React
13 Server Components) to AWS. It builds the project programmatically:
14 the RSC server runs on a
15 [Lambda Web Function](/aws/compute/web-functions) and streams its responses,
16 and the client output — including SSG-prerendered pages — is served
17 from a private S3 bucket through CloudFront. No `waku.config.ts`
18 edits are required — if you have one it loads natively — and there is
19 no adapter to configure and no build command to run.
20
21 ## Install
22
23 The build integration is not bundled with alchemy. Install
24 `@alchemy.run/frontend-frameworks`; the resource loads its `/waku`
25 and `/waku/node` exports from your project at deploy time. It is only
26 used at build time, so a dev dependency is enough:
27
28 <PackageManagers dev={devDeps} />
29
30 ## Configure Waku
31
32 No framework config is required — a fresh Waku project deploys
33 as-is. If your project has a `waku.config.ts`, Alchemy loads it
34 natively (exactly as Waku's own CLI does) and uses it as the base
35 config — including Vite plugins under its `vite` field:
36
37 ```typescript
38 // waku.config.ts
39 import { defineConfig } from "waku/config";
40 import tsconfigPaths from "vite-tsconfig-paths";
41
42 export default defineConfig({
43 basePath: "/",
44 vite: {
45 plugins: [tsconfigPaths()],
46 },
47 });
48 ```
49
50 `waku.config.*` is the home for static configuration. For deploy-time
51 values — anything that varies by stage — the `waku` prop merges
52 overrides over the file, per key:
53
54 ```typescript
55 export const Website = AWS.Website.Waku("Website", {
56 waku: {
57 basePath: "/docs/",
58 },
59 });
60 ```
61
62 The one key Alchemy owns is `unstable_adapter` — setting it fails the
63 build with an actionable error.
64
65 :::note
66 Vite configuration must live in `waku.config.ts`'s `vite` field —
67 a standalone `vite.config.ts` is not loaded, same as Waku's own CLI.
68 :::
69
70 ## Declare the Website
71
72 Declare the site as a module-level const (rather than inline in the
73 Stack):
74
75 ```typescript
76 // alchemy.run.ts
77 import * as AWS from "@alchemy.run/aws";
78
79 export const Website = AWS.Website.Waku("Website");
80 ```
81
82 ## Add it to the Stack
83
84 Yield the site from your Stack and return its URL:
85
86 ```typescript
87 // alchemy.run.ts
88 import * as Alchemy from "alchemy";
89 import * as Effect from "effect/Effect";
90
91 export default Alchemy.Stack(
92 "MyWakuSite",
93 {
94 providers: AWS.providers(),
95 state: AWS.state(),
96 },
97 Effect.gen(function* () {
98 const site = yield* Website;
99 return { url: site.url };
100 }),
101 );
102 ```
103
104 Pages rendered as `"static"` are generated at build time, uploaded
105 to S3, and served from the edge; dynamic pages and API routes stream
106 from the server.
107
108 See
109 [examples/aws-website-waku](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-website-waku)
110 for the checked-in example.
111
112 ## Add environment variables
113
114 The server function's environment is configured under `env` — plain
115 values, or outputs from other resources in the Stack:
116
117 ```diff lang="typescript"
118 // alchemy.run.ts
119 export const Website = AWS.Website.Waku("Website", {
120 + env: {
121 + GREETING: "Hello from alchemy",
122 + API_BASE: api.url,
123 + },
124 });
125 ```
126
127 The values are set on the server at deploy time and injected into the
128 dev server's process environment under `alchemy dev`, so server code
129 reads the same values in both modes.
130
131 ## Read the environment in server code
132
133 Server components and API routes read the environment through waku's
134 `getEnv` — on AWS it is backed by the server's `process.env` at
135 request time, and it keeps page modules portable across deploy
136 targets:
137
138 ```typescript
139 // src/pages/index.tsx
140 import { getEnv } from "waku";
141
142 export default async function HomePage() {
143 const greeting = getEnv("GREETING") ?? "hello";
144 return <h1>{greeting}</h1>;
145 }
146
147 export const getConfig = async () => ({ render: "dynamic" }) as const;
148 ```
149
150 ## Run on a Lambda Function
151
152 Web Functions run in a subset of Regions. Elsewhere, set
153 `server: "function"`: the app builds with the `/waku/aws` deploy target
154 and runs on a Lambda Function behind a streaming Function URL, tuned with
155 `memorySize`, `architecture`, and `runtime`:
156
157 ```diff lang="typescript"
158 // alchemy.run.ts
159 export const Website = AWS.Website.Waku("Website", {
160 + server: "function",
161 + memorySize: 2048,
162 });
163 ```
164
165 ## Local dev
166
167 ```sh
168 bun alchemy dev
169 ```
170
171 `alchemy dev` runs Waku's own dev server (native HMR) instead of
172 deploying; `site.url` is the local address and no AWS resources are
173 created. Wrap the site in `Alchemy.remote()` to deploy the real
174 infrastructure even during dev.
175
176 ## Custom domain
177
178 ```typescript
179 const site = yield* AWS.Website.Waku("Web", {
180 domain: { name: "app.example.com" },
181 });
182 ```
183
184 The hosted zone is inferred from the hostname. Pass `hostedZoneId` to
185 pin it when several zones could match.