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

main
mdx 207 lines 6.04 KB
Raw
1 ---
2 title: Waku
3 description: Deploy a Waku app to Cloudflare Workers with Cloudflare.Website.Waku — RSC server in the Worker, SSG pages as static assets, and a custom-entry seam for Durable Objects.
4 sidebar:
5 order: 12
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Cloudflare.Website.Waku` deploys a [Waku](https://waku.gg) app as a
13 Cloudflare Worker. It builds the project programmatically: the React
14 Server Components server bundle deploys as the Worker script, and the
15 client output — including SSG-prerendered pages — deploys as static
16 assets. No `waku.config.ts` edits are required — if you have one it
17 loads natively — and there is no Wrangler file and no build command
18 to run.
19
20 ## Install
21
22 The build integration is not bundled with alchemy. Install
23 `@alchemy.run/frontend-frameworks`; the resource loads its `/waku`
24 export from your project at deploy time. It is only used at build time,
25 so a dev dependency is enough:
26
27 <PackageManagers dev={devDeps} />
28
29 ## Configure Waku
30
31 No framework config is required — a fresh Waku project deploys
32 as-is. If your project has a `waku.config.ts`, Alchemy loads it
33 natively (exactly as Waku's own CLI does) and uses it as the base
34 config — including Vite plugins under its `vite` field:
35
36 ```typescript
37 // waku.config.ts
38 import { defineConfig } from "waku/config";
39 import tsconfigPaths from "vite-tsconfig-paths";
40
41 export default defineConfig({
42 basePath: "/",
43 vite: {
44 plugins: [tsconfigPaths()],
45 },
46 });
47 ```
48
49 `waku.config.*` is the home for static configuration. For deploy-time
50 values — anything that varies by stage — the `waku` prop merges
51 overrides over the file, per key:
52
53 ```typescript
54 export const Website = Cloudflare.Website.Waku("Website", {
55 waku: {
56 basePath: "/docs/",
57 },
58 });
59 ```
60
61 The one key Alchemy owns is `unstable_adapter` — setting it fails the
62 build with an actionable error.
63
64 :::note
65 Vite configuration must live in `waku.config.ts`'s `vite` field —
66 a standalone `vite.config.ts` is not loaded, same as Waku's own CLI.
67 :::
68
69 ## Declare the Website
70
71 Declare the site as a module-level const (rather than inline in the
72 Stack) and derive the typed shape of its bindings from it:
73
74 ```typescript
75 // alchemy.run.ts
76 import * as Cloudflare from "@alchemy.run/cloudflare";
77
78 export const Website = Cloudflare.Website.Waku("Website");
79
80 export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;
81 ```
82
83 `WebsiteEnv` is the typed shape of the Worker's bindings, derived
84 from the class — you'll import it into your Waku code in
85 [Read bindings in server code](#read-bindings-in-server-code).
86
87 ## Add it to the Stack
88
89 Yield the class from your Stack and return its URL:
90
91 ```typescript
92 // alchemy.run.ts
93 import * as Alchemy from "alchemy";
94 import * as Effect from "effect/Effect";
95
96 export default Alchemy.Stack(
97 "MyWakuSite",
98 {
99 providers: Cloudflare.providers(),
100 state: Cloudflare.state(),
101 },
102 Effect.gen(function* () {
103 const site = yield* Website;
104 return { url: site.url };
105 }),
106 );
107 ```
108
109 Waku's server runtime uses `AsyncLocalStorage`, so the `nodejs_als`
110 compatibility flag is added automatically — you don't need to pass
111 it. SSG pages are served at their extensionless URLs (`/about`) via
112 the default `drop-trailing-slash` asset handling.
113
114 During `alchemy dev`, Waku's dev server runs with SSR executing in
115 workerd, so server code sees the same runtime and the same real
116 bindings it will have in production.
117
118 See
119 [examples/cloudflare-website-waku](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-website-waku)
120 for the checked-in example.
121
122 ## Add bindings
123
124 The resource returns a plain `Worker`, so `env` accepts the full
125 binding vocabulary — KV namespaces, R2 buckets, Durable Objects,
126 secrets:
127
128 ```diff lang="typescript"
129 // alchemy.run.ts
130 +import * as Config from "effect/Config";
131
132 +export const Uploads = Cloudflare.R2.Bucket("Uploads");
133
134 export const Website = Cloudflare.Website.Waku("Website", {
135 + env: {
136 + UPLOADS: Uploads,
137 + API_KEY: Config.Redacted("API_KEY"),
138 + },
139 });
140 ```
141
142 `Uploads` is a description, not a deploy — Alchemy provisions the
143 real bucket because the Website binds it. `Config.Redacted` reads
144 `API_KEY` from your environment at deploy time and binds it as a
145 Worker secret — see [Secrets & env](/cloudflare/security/secrets-env).
146
147 ## Read bindings in server code
148
149 Server components and API routes read bindings from the
150 `cloudflare:workers` env at request time. Use a guarded dynamic
151 import — Waku's SSG step renders static pages in Node, where a
152 top-level `import { env } from "cloudflare:workers"` cannot
153 resolve — and type the result with the inferred env type:
154
155 ```typescript
156 // src/lib/env.ts
157 import type { WebsiteEnv } from "../../alchemy.run.ts";
158
159 export const getEnv = async (): Promise<WebsiteEnv> => {
160 const { env } = await import("cloudflare:workers");
161 return env as WebsiteEnv;
162 };
163 ```
164
165 Server code calls it per request:
166
167 ```typescript
168 // src/pages/api/upload.ts
169 import { getEnv } from "../../lib/env.ts";
170
171 export const POST = async (request: Request) => {
172 const env = await getEnv();
173 await env.UPLOADS.put("hello.txt", await request.text());
174 return Response.json({ ok: true });
175 };
176 ```
177
178 `env.UPLOADS` is typed as an R2 bucket and `env.API_KEY` as a
179 string — renaming a binding in `alchemy.run.ts` is a type error in
180 your server code.
181
182 ## Custom Worker entry (Durable Objects)
183
184 By default the deployed Worker entry is Waku's own RSC server entry.
185 When the Worker must export more than Waku's fetch handler — Durable
186 Object classes, additional handlers — point `main` at your own module
187 that wraps Waku's handler and re-exports the extras:
188
189 ```typescript
190 // src/worker-entry.ts
191 import wakuHandler from "virtual:waku/server-entry";
192 export class Counter extends DurableObject {}
193 export default {
194 fetch: (request, env, ctx) => wakuHandler.fetch(request, env, ctx),
195 };
196 ```
197
198 ```typescript
199 export const Website = Cloudflare.Website.Waku("Website", {
200 main: "src/worker-entry.ts",
201 env: {
202 COUNTER: Cloudflare.DurableObject("Counter", {
203 className: "Counter",
204 }),
205 },
206 });
207 ```