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

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