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

main
mdx 267 lines 7.94 KB
Raw
1 ---
2 title: React Router
3 description: Deploy React Router v8 (framework mode) to Fly with Fly.Website.ReactRouter — SSR on a Machine, client assets baked into the image, 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 `Fly.Website.ReactRouter` deploys a
13 [React Router](https://reactrouter.com) v8 app in framework mode to Fly.
14 React Router builds through Vite, so Alchemy runs your project's own
15 build: the SSR server runs as a Node [`Fly.Service`](/fly/compute/services)
16 on a Machine, and client assets are baked into the image and served
17 first. Omit `app` and Alchemy creates a
18 [`Fly.App`](/fly/compute/apps) plus a shared IPv4 so
19 `https://{app}.fly.dev` answers. No adapter, no `fly.toml`.
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 Fly deploy
63 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 Fly from "@alchemy.run/fly";
87
88 export const Website = Fly.Website.ReactRouter("Website");
89 ```
90
91 Pass `app` to put the site on an existing `Fly.App`. `rootDir` is the
92 project root — the directory holding `package.json`, `vite.config.*`,
93 and `react-router.config.ts`. It defaults to `"."`, so set it only when
94 the app does not sit next to `alchemy.run.ts`:
95
96 ```typescript
97 export const Website = Fly.Website.ReactRouter("Website", {
98 rootDir: "./web",
99 });
100 ```
101
102 ## Add it to the Stack
103
104 Yield the site from your Stack and return its URL:
105
106 ```typescript
107 // alchemy.run.ts
108 import * as Alchemy from "alchemy";
109 import * as Effect from "effect/Effect";
110
111 export default Alchemy.Stack(
112 "MyReactRouterSite",
113 {
114 providers: Fly.providers(),
115 state: Alchemy.localState(),
116 },
117 Effect.gen(function* () {
118 const site = yield* Website;
119 return { url: site.url };
120 }),
121 );
122 ```
123
124 Requests matching a built client asset are served first; everything
125 else — SSR routes, loaders, actions, resource routes — falls through to
126 the Node handler on the Machine.
127
128 The live `url` is `https://{app}.fly.dev`. `site.app`,
129 `site.service`, `site.ip`, and `site.certificate` are the Fly
130 resources underneath — `undefined` during `alchemy dev`.
131
132 See the [React Router API reference](/providers/fly/website/reactrouter)
133 for every prop and attribute.
134
135 ## How the two build outputs are deployed
136
137 `react-router build` writes two directories, and both land in the
138 Machine image:
139
140 ```
141 build/
142 ├── client/ -> baked into the image, served first
143 └── server/ -> wrapped as a Node HTTP server on port 3000
144 ```
145
146 `build/client` holds the hashed browser bundles plus everything you put
147 in `public/`. `build/server/index.js` is a `ServerBuild` manifest, not a
148 request handler, so Alchemy wraps it with `createRequestHandler` during
149 the build and emits a Node serve entry — that process is the
150 [`Fly.Service`](/fly/compute/services).
151
152 If you set Vite's `base`, set React Router's `basename` to the same
153 prefix: the client directory maps onto the site root one-for-one, so the
154 paths the SSR document emits have to be the paths the image was given.
155
156 ## Add environment variables
157
158 Process environment is a top-level `env` map — plain strings, or
159 `Redacted` values:
160
161 ```diff lang="typescript"
162 // alchemy.run.ts
163 export const Website = Fly.Website.ReactRouter("Website", {
164 + env: {
165 + API_BASE: "https://api.example.com",
166 + },
167 });
168 ```
169
170 The values are copied onto `process.env` before the build and the
171 dev server, and onto the Machine at deploy time, so server code
172 reads the same keys in both modes. Client inlining is whatever Vite
173 does (`VITE_` prefixes).
174
175 An output from another resource only exists once that resource is
176 yielded, so declare the site inside the Stack generator instead:
177
178 ```typescript
179 // alchemy.run.ts
180 Effect.gen(function* () {
181 const api = yield* Api;
182
183 const site = yield* Fly.Website.ReactRouter("Website", {
184 env: { API_BASE: api.url },
185 });
186
187 return { url: site.url };
188 });
189 ```
190
191 ## Read the environment in a loader
192
193 The React Router server is a plain Node process. Loaders and
194 actions read the environment from `process.env`:
195
196 ```typescript
197 // app/routes/home.tsx
198 export function loader() {
199 return { apiBase: process.env.API_BASE ?? "unset" };
200 }
201 ```
202
203 Values prefixed `VITE_` are inlined into the client bundle at build time
204 instead, as `import.meta.env.VITE_*` — set those in the shell that runs
205 `alchemy deploy`, not in `env`.
206
207 ## Read the environment in a resource route
208
209 A route module with no default export is a resource route, served by the
210 same Node process:
211
212 ```typescript
213 // app/routes/api.hello.ts
214 export function loader() {
215 return new Response(process.env.API_BASE ?? "unset");
216 }
217 ```
218
219 ## Build configuration
220
221 The build runs through your project's own `vite.config.ts` and
222 `react-router.config.ts`. A custom `buildDirectory` just works — the
223 integration observes the directory from the resolved Vite config, so
224 there is nothing to mirror on the resource.
225
226 ## Local dev
227
228 ```sh
229 bun alchemy dev
230 ```
231
232 `alchemy dev` runs React Router's own Vite dev server (native HMR)
233 instead of deploying; `site.url` is the local address and no Fly
234 resources are created. Wrap the site in `Alchemy.remote()` to deploy the
235 live App and Service even during dev:
236
237 ```typescript
238 export const Website = Fly.Website.ReactRouter("Website").pipe(
239 Alchemy.remote(),
240 );
241 ```
242
243 ## React Server Components
244
245 RSC is not supported yet. React Router's `unstable` RSC plugin — and
246 the `future.v8_viteEnvironmentApi` flag — emit more than one server
247 environment, and this resource assembles a single Node entry. A build
248 that produces no single server entry fails with an actionable error
249 rather than deploying something broken.
250
251 ## Custom domain
252
253 ```typescript
254 const site = yield* Fly.Website.ReactRouter("Web", {
255 domain: "app.example.com",
256 });
257 ```
258
259 `domain` requests ACME (`Fly.Certificate`) on the App. `url`
260 becomes `https://app.example.com`. Point DNS at the App first — v1
261 does not create DNS records.
262
263 ## Where next
264
265 - [React Router API reference](/providers/fly/website/reactrouter)
266 - [Apps](/fly/compute/apps) and [Services](/fly/compute/services)
267 - [IPs & certificates](/fly/networking)