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 Hetzner with Hetzner.Website.Waku — RSC server as a systemd unit on port 3000, SSG pages baked into the unit, 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 | `Hetzner.Website.Waku` deploys a [Waku](https://waku.gg) app (React |
| 13 | Server Components) to a Hetzner Cloud Server. It builds the project |
| 14 | programmatically: the RSC server runs as a systemd |
| 15 | [`Hetzner.Service`](/hetzner/compute/services) on port 3000, and the |
| 16 | client output — including SSG-prerendered pages — is baked into the |
| 17 | unit. Omit `server` and Alchemy creates a `cpx12` Ubuntu 24.04 box |
| 18 | in `fsn1`. The live URL is `http://{ipv4}:3000` — the Service has |
| 19 | no TLS. No `waku.config.ts` edits are required — if you have one it |
| 20 | loads natively — and there is no adapter to configure and no build |
| 21 | command to run. |
| 22 | |
| 23 | ## Install |
| 24 | |
| 25 | The build integration is not bundled with alchemy. Install |
| 26 | `@alchemy.run/frontend-frameworks`; the resource loads its `/waku` |
| 27 | and `/waku/node` exports from your project at deploy time. It is only |
| 28 | used at build time, so a dev dependency is enough: |
| 29 | |
| 30 | <PackageManagers dev={devDeps} /> |
| 31 | |
| 32 | ## Configure Waku |
| 33 | |
| 34 | No framework config is required — a fresh Waku project deploys |
| 35 | as-is. If your project has a `waku.config.ts`, Alchemy loads it |
| 36 | natively (exactly as Waku's own CLI does) and uses it as the base |
| 37 | config — including Vite plugins under its `vite` field: |
| 38 | |
| 39 | ```typescript |
| 40 | // waku.config.ts |
| 41 | import tailwindcss from "@tailwindcss/vite"; |
| 42 | import { defineConfig } from "waku/config"; |
| 43 | |
| 44 | export default defineConfig({ |
| 45 | basePath: "/", |
| 46 | vite: { |
| 47 | plugins: [tailwindcss()], |
| 48 | }, |
| 49 | }); |
| 50 | ``` |
| 51 | |
| 52 | Options set on the resource (`srcDir`, `distDir`, `basePath`) merge |
| 53 | over the file, per key. The one key Alchemy owns is |
| 54 | `unstable_adapter` — the Node deploy target sets it. Setting it |
| 55 | fails the build with an actionable error. |
| 56 | |
| 57 | :::note |
| 58 | Vite configuration must live in `waku.config.ts`'s `vite` field — |
| 59 | a standalone `vite.config.ts` is not loaded, same as Waku's own CLI. |
| 60 | ::: |
| 61 | |
| 62 | ## Declare the Website |
| 63 | |
| 64 | Declare the site as a module-level const (rather than inline in the |
| 65 | Stack): |
| 66 | |
| 67 | ```typescript |
| 68 | // alchemy.run.ts |
| 69 | import * as Hetzner from "@alchemy.run/hetzner"; |
| 70 | |
| 71 | export const Website = Hetzner.Website.Waku("Website"); |
| 72 | ``` |
| 73 | |
| 74 | Pass `server` to host the site on an existing |
| 75 | [`Hetzner.Server`](/hetzner/compute/servers) — several sites and |
| 76 | APIs can share one box. `rootDir` defaults to `"."`. |
| 77 | |
| 78 | ## Add it to the Stack |
| 79 | |
| 80 | Yield the site from your Stack and return its URL: |
| 81 | |
| 82 | ```typescript |
| 83 | // alchemy.run.ts |
| 84 | import * as Alchemy from "alchemy"; |
| 85 | import * as Effect from "effect/Effect"; |
| 86 | |
| 87 | export default Alchemy.Stack( |
| 88 | "MyWakuSite", |
| 89 | { |
| 90 | providers: Hetzner.providers(), |
| 91 | state: Alchemy.localState(), |
| 92 | }, |
| 93 | Effect.gen(function* () { |
| 94 | const site = yield* Website; |
| 95 | return { url: site.url }; |
| 96 | }), |
| 97 | ); |
| 98 | ``` |
| 99 | |
| 100 | Pages rendered as `"static"` are generated at build time and baked |
| 101 | into the unit; dynamic pages and API routes run on the Server. |
| 102 | Prerendered pages are served at their extensionless URLs (`/about`, |
| 103 | not `/about/`). |
| 104 | |
| 105 | The live `url` is `http://{ipv4}:3000`. `site.server` and |
| 106 | `site.service` are the Hetzner resources underneath — `undefined` |
| 107 | during `alchemy dev`. |
| 108 | |
| 109 | See the [Waku API reference](/providers/hetzner/website/waku) for |
| 110 | every prop and attribute. |
| 111 | |
| 112 | ## Add environment variables |
| 113 | |
| 114 | Process environment is a top-level `env` map — plain strings, or |
| 115 | `Redacted` values: |
| 116 | |
| 117 | ```diff lang="typescript" |
| 118 | // alchemy.run.ts |
| 119 | export const Website = Hetzner.Website.Waku("Website", { |
| 120 | + env: { |
| 121 | + GREETING: "Hello from alchemy", |
| 122 | + API_BASE: "https://api.example.com", |
| 123 | + }, |
| 124 | }); |
| 125 | ``` |
| 126 | |
| 127 | The values are copied onto `process.env` before the build and the |
| 128 | dev server, and onto the systemd unit at deploy time, so server |
| 129 | code reads the same keys in both modes. Client inlining is whatever |
| 130 | Vite does (`VITE_` prefixes). |
| 131 | |
| 132 | ## Read the environment in server code |
| 133 | |
| 134 | The RSC server is a plain Node process. Server components and API |
| 135 | routes read `process.env` (Waku's `getEnv` reads the same values): |
| 136 | |
| 137 | ```typescript |
| 138 | // src/pages/index.tsx |
| 139 | export default async function HomePage() { |
| 140 | const greeting = process.env.GREETING ?? "hello"; |
| 141 | return <h1>{greeting}</h1>; |
| 142 | } |
| 143 | |
| 144 | export const getConfig = async () => ({ render: "dynamic" }) as const; |
| 145 | ``` |
| 146 | |
| 147 | ## Local dev |
| 148 | |
| 149 | ```sh |
| 150 | bun alchemy dev |
| 151 | ``` |
| 152 | |
| 153 | `alchemy dev` runs Waku's own dev server (native HMR) instead of |
| 154 | deploying; `site.url` is the local address and no Hetzner resources |
| 155 | are created. Wrap the site in `Alchemy.remote()` to deploy the live |
| 156 | Server and Service even during dev: |
| 157 | |
| 158 | ```typescript |
| 159 | export const Website = Hetzner.Website.Waku("Website").pipe( |
| 160 | Alchemy.remote(), |
| 161 | ); |
| 162 | ``` |
| 163 | |
| 164 | ## Custom domain |
| 165 | |
| 166 | ```typescript |
| 167 | const zone = yield* Hetzner.Zone("dns", { name: "example.com" }); |
| 168 | const site = yield* Hetzner.Website.Waku("Web", { |
| 169 | domain: "app.example.com", |
| 170 | zone, |
| 171 | }); |
| 172 | ``` |
| 173 | |
| 174 | `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns) |
| 175 | — the Website does not create one. It adds an A record pointing at |
| 176 | the Server's public IPv4. `url` becomes `http://app.example.com:3000`. |
| 177 | There is no TLS on the Service. |
| 178 | |
| 179 | ## Where next |
| 180 | |
| 181 | - [Waku API reference](/providers/hetzner/website/waku) |
| 182 | - [Servers](/hetzner/compute/servers) and |
| 183 | [Services](/hetzner/compute/services) |
| 184 | - [DNS](/hetzner/networking/dns) |