@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

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