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

main
mdx 274 lines 8.28 KB
Raw
1 ---
2 title: React Router
3 description: Deploy React Router v8 (framework mode) to Hetzner with Hetzner.Website.ReactRouter — SSR as a systemd unit on port 3000, client assets baked into the unit, and React Router's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 7
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Hetzner.Website.ReactRouter` deploys a
13 [React Router](https://reactrouter.com) v8 app in framework mode to a
14 Hetzner Cloud Server. React Router builds through Vite, so Alchemy runs
15 your project's own build: the SSR server runs as a systemd
16 [`Hetzner.Service`](/hetzner/compute/services) on port 3000, and
17 client assets are baked into the unit and served first. Omit `server`
18 and Alchemy creates a `cpx12` Ubuntu 24.04 box in `fsn1`. The live URL
19 is `http://{ipv4}:3000` — the Service has no TLS. No adapter.
20
21 ## Install
22
23 The build integration is not bundled with alchemy. Install
24 `@alchemy.run/frontend-frameworks`; the resource loads its
25 `/react-router` and `/react-router/node` exports from your project at
26 deploy time. It is only used at build time, so a dev dependency is
27 enough:
28
29 <PackageManagers dev={devDeps} />
30
31 The React Router side is whatever `npx create-react-router@latest`
32 scaffolds — `react-router`, `@react-router/dev`, `@react-router/node`,
33 `isbot`, and `vite`. Keep `@react-router/node` and `isbot` in
34 `dependencies`: React Router picks its default `entry.server` by reading
35 them from your `package.json`, and installs `isbot` on the fly if it is
36 missing.
37
38 ## Configure Vite
39
40 Your `vite.config.ts` stays what the React Router scaffold gives
41 you — no adapter, no server preset. Vite plugins like Tailwind go in
42 `plugins` as usual:
43
44 ```typescript
45 // vite.config.ts
46 import { reactRouter } from "@react-router/dev/vite";
47 import tailwindcss from "@tailwindcss/vite";
48 import { defineConfig } from "vite";
49
50 export default defineConfig({
51 plugins: [tailwindcss(), reactRouter()],
52 });
53 ```
54
55 `reactRouter()` owns routing, typegen, and both build environments.
56 Alchemy drives the same two passes `react-router build` runs, wraps the
57 server manifest with `createRequestHandler`, and packages the resulting
58 fetch handler as a Node HTTP server on port 3000.
59
60 :::caution[Remove @cloudflare/vite-plugin if present]
61 The React Router CLI adds `@cloudflare/vite-plugin` when you pick the
62 Cloudflare template. It builds for workerd, not Node, so a Hetzner
63 deploy needs it gone:
64
65 ```diff lang="typescript"
66 // vite.config.ts
67 -import { cloudflare } from "@cloudflare/vite-plugin";
68 import { reactRouter } from "@react-router/dev/vite";
69 import { defineConfig } from "vite";
70
71 export default defineConfig({
72 - plugins: [cloudflare({ viteEnvironment: { name: "ssr" } }), reactRouter()],
73 + plugins: [reactRouter()],
74 });
75 ```
76
77 :::
78
79 ## Declare the Website
80
81 Declare the site as a module-level const (rather than inline in the
82 Stack):
83
84 ```typescript
85 // alchemy.run.ts
86 import * as Hetzner from "@alchemy.run/hetzner";
87
88 export const Website = Hetzner.Website.ReactRouter("Website");
89 ```
90
91 Pass `server` to host the site on an existing
92 [`Hetzner.Server`](/hetzner/compute/servers) — several sites and
93 APIs can share one box. `rootDir` is the project root — the directory
94 holding `package.json`, `vite.config.*`, and `react-router.config.ts`.
95 It defaults to `"."`, so set it only when the app does not sit next to
96 `alchemy.run.ts`:
97
98 ```typescript
99 export const Website = Hetzner.Website.ReactRouter("Website", {
100 rootDir: "./web",
101 });
102 ```
103
104 ## Add it to the Stack
105
106 Yield the site from your Stack and return its URL:
107
108 ```typescript
109 // alchemy.run.ts
110 import * as Alchemy from "alchemy";
111 import * as Effect from "effect/Effect";
112
113 export default Alchemy.Stack(
114 "MyReactRouterSite",
115 {
116 providers: Hetzner.providers(),
117 state: Alchemy.localState(),
118 },
119 Effect.gen(function* () {
120 const site = yield* Website;
121 return { url: site.url };
122 }),
123 );
124 ```
125
126 Requests matching a built client asset are served first; everything
127 else — SSR routes, loaders, actions, resource routes — falls through to
128 the Node handler on the Server.
129
130 The live `url` is `http://{ipv4}:3000`. `site.server` and
131 `site.service` are the Hetzner resources underneath — `undefined`
132 during `alchemy dev`.
133
134 See the
135 [React Router API reference](/providers/hetzner/website/reactrouter)
136 for every prop and attribute.
137
138 ## How the two build outputs are deployed
139
140 `react-router build` writes two directories, and both land in the
141 systemd unit:
142
143 ```
144 build/
145 ├── client/ -> baked into the unit, served first
146 └── server/ -> wrapped as a Node HTTP server on port 3000
147 ```
148
149 `build/client` holds the hashed browser bundles plus everything you put
150 in `public/`. `build/server/index.js` is a `ServerBuild` manifest, not a
151 request handler, so Alchemy wraps it with `createRequestHandler` during
152 the build and emits a Node serve entry — that process is the
153 [`Hetzner.Service`](/hetzner/compute/services).
154
155 If you set Vite's `base`, set React Router's `basename` to the same
156 prefix: the client directory maps onto the site root one-for-one, so the
157 paths the SSR document emits have to be the paths the unit was given.
158
159 ## Add environment variables
160
161 Process environment is a top-level `env` map — plain strings, or
162 `Redacted` values:
163
164 ```diff lang="typescript"
165 // alchemy.run.ts
166 export const Website = Hetzner.Website.ReactRouter("Website", {
167 + env: {
168 + API_BASE: "https://api.example.com",
169 + },
170 });
171 ```
172
173 The values are copied onto `process.env` before the build and the
174 dev server, and onto the systemd unit at deploy time, so server
175 code reads the same keys in both modes. Client inlining is whatever
176 Vite does (`VITE_` prefixes).
177
178 An output from another resource only exists once that resource is
179 yielded, so declare the site inside the Stack generator instead:
180
181 ```typescript
182 // alchemy.run.ts
183 Effect.gen(function* () {
184 const api = yield* Api;
185
186 const site = yield* Hetzner.Website.ReactRouter("Website", {
187 env: { API_BASE: api.url },
188 });
189
190 return { url: site.url };
191 });
192 ```
193
194 ## Read the environment in a loader
195
196 The React Router server is a plain Node process. Loaders and
197 actions read the environment from `process.env`:
198
199 ```typescript
200 // app/routes/home.tsx
201 export function loader() {
202 return { apiBase: process.env.API_BASE ?? "unset" };
203 }
204 ```
205
206 Values prefixed `VITE_` are inlined into the client bundle at build time
207 instead, as `import.meta.env.VITE_*` — set those in the shell that runs
208 `alchemy deploy`, not in `env`.
209
210 ## Read the environment in a resource route
211
212 A route module with no default export is a resource route, served by the
213 same Node process:
214
215 ```typescript
216 // app/routes/api.hello.ts
217 export function loader() {
218 return new Response(process.env.API_BASE ?? "unset");
219 }
220 ```
221
222 ## Build configuration
223
224 The build runs through your project's own `vite.config.ts` and
225 `react-router.config.ts`. A custom `buildDirectory` just works — the
226 integration observes the directory from the resolved Vite config, so
227 there is nothing to mirror on the resource.
228
229 ## Local dev
230
231 ```sh
232 bun alchemy dev
233 ```
234
235 `alchemy dev` runs React Router's own Vite dev server (native HMR)
236 instead of deploying; `site.url` is the local address and no Hetzner
237 resources are created. Wrap the site in `Alchemy.remote()` to deploy
238 the live Server and Service even during dev:
239
240 ```typescript
241 export const Website = Hetzner.Website.ReactRouter("Website").pipe(
242 Alchemy.remote(),
243 );
244 ```
245
246 ## React Server Components
247
248 RSC is not supported yet. React Router's `unstable` RSC plugin — and
249 the `future.v8_viteEnvironmentApi` flag — emit more than one server
250 environment, and this resource assembles a single Node entry. A build
251 that produces no single server entry fails with an actionable error
252 rather than deploying something broken.
253
254 ## Custom domain
255
256 ```typescript
257 const zone = yield* Hetzner.Zone("dns", { name: "example.com" });
258 const site = yield* Hetzner.Website.ReactRouter("Web", {
259 domain: "app.example.com",
260 zone,
261 });
262 ```
263
264 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
265 — the Website does not create one. It adds an A record pointing at
266 the Server's public IPv4. `url` becomes `http://app.example.com:3000`.
267 There is no TLS on the Service.
268
269 ## Where next
270
271 - [React Router API reference](/providers/hetzner/website/reactrouter)
272 - [Servers](/hetzner/compute/servers) and
273 [Services](/hetzner/compute/services)
274 - [DNS](/hetzner/networking/dns)