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 Railway with Railway.Website.Waku — RSC server on a container Service, SSG pages in 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 | `Railway.Website.Waku` deploys a [Waku](https://waku.gg) app (React |
| 13 | Server Components) to Railway. It builds the project programmatically: |
| 14 | the RSC server plus SSG pages run on one |
| 15 | [`Railway.Service`](/railway/compute/services). Alchemy creates a |
| 16 | [`Railway.Project`](/railway/compute/projects) if you omit |
| 17 | `project`. The URL is the generated `*.up.railway.app` hostname. No |
| 18 | `waku.config.ts` edits are required — if you have one it loads |
| 19 | natively — and there is no adapter to configure and no build command |
| 20 | 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 Railway from "@alchemy.run/railway"; |
| 69 | |
| 70 | export const Website = Railway.Website.Waku("Website"); |
| 71 | ``` |
| 72 | |
| 73 | Pass `project` to put the Service in an existing `Railway.Project`. |
| 74 | `rootDir` 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: Railway.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 Service. |
| 100 | SSG pages are served at their extensionless URLs (`/about`). |
| 101 | |
| 102 | The live `url` is `https://{name}.up.railway.app`. `site.service` |
| 103 | and `site.project` are the Railway resources underneath — |
| 104 | `undefined` during `alchemy dev`. |
| 105 | |
| 106 | See the [Waku API reference](/providers/railway/website/waku) for |
| 107 | every 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 = Railway.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 Service 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 Railway resources |
| 152 | are created. Wrap the site in |
| 153 | `Alchemy.remote()` to deploy the live Service even during dev: |
| 154 | |
| 155 | ```typescript |
| 156 | export const Website = Railway.Website.Waku("Website").pipe(Alchemy.remote()); |
| 157 | ``` |
| 158 | |
| 159 | ## Custom domain |
| 160 | |
| 161 | ```typescript |
| 162 | const site = yield* Railway.Website.Waku("Web", { |
| 163 | domain: "app.example.com", |
| 164 | }); |
| 165 | ``` |
| 166 | |
| 167 | `domain` attaches a [`Railway.CustomDomain`](/railway/networking) |
| 168 | (`targetPort` 3000). `url` becomes `https://app.example.com` |
| 169 | instead of the generated `*.up.railway.app`. |
| 170 | |
| 171 | ## Where next |
| 172 | |
| 173 | - [Waku API reference](/providers/railway/website/waku) |
| 174 | - [Projects](/railway/compute/projects) and |
| 175 | [Services](/railway/compute/services) |
| 176 | - [Custom domains](/railway/networking) |