The best way to control Claude Code, Codex and more from any computer or phone
| 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. |