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
| 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 | ``` |