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

main
mdx 266 lines 7.38 KB
Raw
1 ---
2 title: TanStack Start
3 description: Deploy TanStack Start (React or Solid) to Railway with Railway.Website.TanStackStart — SSR on a container Service, client assets in the image, and TanStack Start's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 8
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Railway.Website.TanStackStart` deploys a
13 [TanStack Start](https://tanstack.com/start) app to Railway. TanStack
14 Start is pure Vite, so Alchemy runs your project's own `vite build`:
15 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 `/tanstack-start` and `/tanstack-start/node` exports from your project
26 at deploy time. It is only used at build time, so a dev dependency is
27 enough:
28
29 <PackageManagers dev={devDeps} />
30
31 ## Configure Vite
32
33 Your `vite.config.ts` stays what TanStack Start's scaffold gives
34 you — no adapter, no deployment preset. Vite plugins like Tailwind
35 go in `plugins` as usual:
36
37 ```typescript
38 // vite.config.ts
39 import tailwindcss from "@tailwindcss/vite";
40 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
41 import viteReact from "@vitejs/plugin-react";
42 import { defineConfig } from "vite";
43
44 export default defineConfig({
45 plugins: [tailwindcss(), tanstackStart(), viteReact()],
46 });
47 ```
48
49 Alchemy drives that config's `builder.buildApp()` and forces the SSR
50 bundle to be self-contained, then wraps its fetch handler as a Node
51 HTTP server on port 3000.
52
53 :::caution[Remove @cloudflare/vite-plugin if present]
54 The TanStack CLI adds `@cloudflare/vite-plugin` when scaffolding a new
55 app. It builds for workerd, not Node, so a Railway deploy needs it
56 gone:
57
58 ```diff lang="typescript"
59 // vite.config.ts
60 -import { cloudflare } from "@cloudflare/vite-plugin";
61 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
62 import viteReact from "@vitejs/plugin-react";
63 import { defineConfig } from "vite";
64
65 export default defineConfig({
66 - plugins: [
67 - cloudflare({ viteEnvironment: { name: "ssr" } }),
68 - tanstackStart(),
69 - viteReact(),
70 - ],
71 + plugins: [tanstackStart(), viteReact()],
72 });
73 ```
74
75 :::
76
77 ## Declare the Website
78
79 Declare the site as a module-level const (rather than inline in the
80 Stack):
81
82 ```typescript
83 // alchemy.run.ts
84 import * as Railway from "@alchemy.run/railway";
85
86 export const Website = Railway.Website.TanStackStart("Website");
87 ```
88
89 Pass `project` to put the Service in an existing `Railway.Project`.
90 `rootDir` is the project root — the directory holding `package.json`
91 and `vite.config.*`. It defaults to `"."`, so set it only when the app
92 does not sit next to `alchemy.run.ts`:
93
94 ```typescript
95 export const Website = Railway.Website.TanStackStart("Website", {
96 rootDir: "./app",
97 });
98 ```
99
100 ## Add it to the Stack
101
102 Yield the site from your Stack and return its URL:
103
104 ```typescript
105 // alchemy.run.ts
106 import * as Alchemy from "alchemy";
107 import * as Effect from "effect/Effect";
108
109 export default Alchemy.Stack(
110 "MyTanStackSite",
111 {
112 providers: Railway.providers(),
113 state: Alchemy.localState(),
114 },
115 Effect.gen(function* () {
116 const site = yield* Website;
117 return { url: site.url };
118 }),
119 );
120 ```
121
122 Requests matching a built client asset are served first; everything
123 else — SSR routes, server routes, server functions — falls through to
124 the Node handler on the Service.
125
126 The live `url` is `https://{name}.up.railway.app`. `site.service`
127 and `site.project` are the Railway resources underneath —
128 `undefined` during `alchemy dev`.
129
130 See the
131 [TanStack Start API reference](/providers/railway/website/tanstackstart)
132 for every prop and attribute.
133
134 ## Add environment variables
135
136 Process environment is a top-level `env` map — plain strings, or
137 `Redacted` values:
138
139 ```diff lang="typescript"
140 // alchemy.run.ts
141 export const Website = Railway.Website.TanStackStart("Website", {
142 + env: {
143 + API_BASE: "https://api.example.com",
144 + },
145 });
146 ```
147
148 The values are copied onto `process.env` before the build and the
149 dev server, and onto the Service at deploy time, so server code
150 reads the same keys in both modes. Client inlining is whatever Vite
151 does (`VITE_` prefixes).
152
153 An output from another resource only exists once that resource is
154 yielded, so declare the site inside the Stack generator instead:
155
156 ```typescript
157 // alchemy.run.ts
158 Effect.gen(function* () {
159 const api = yield* Api;
160
161 const site = yield* Railway.Website.TanStackStart("Website", {
162 env: { API_BASE: api.url },
163 });
164
165 return { url: site.url };
166 });
167 ```
168
169 ## Read the environment in a server function
170
171 The TanStack Start server is a plain Node process, so server
172 functions read the environment from `process.env`:
173
174 ```typescript
175 // src/routes/index.tsx
176 import { createServerFn } from "@tanstack/react-start";
177
178 const getApiBase = createServerFn({ method: "GET" }).handler(() => ({
179 apiBase: process.env.API_BASE ?? "unset",
180 }));
181 ```
182
183 Values prefixed `VITE_` are inlined into the client bundle at build time
184 instead, as `import.meta.env.VITE_*` — set those in the shell that runs
185 `alchemy deploy`, not in `env`.
186
187 ## Read the environment in a server route
188
189 Server routes run on the same Node process and read `process.env` the
190 same way:
191
192 ```typescript
193 // src/routes/api.hello.ts
194 import { createFileRoute } from "@tanstack/react-router";
195
196 export const Route = createFileRoute("/api/hello")({
197 server: {
198 handlers: {
199 GET: () => new Response(process.env.API_BASE ?? "unset"),
200 },
201 },
202 });
203 ```
204
205 ## Build configuration
206
207 The build runs through your project's own `vite.config.ts` — the
208 `tanstackStart()` plugin and everything else in it apply as-is. Keep
209 vite's default `build.outDir` (`dist`); the integration reads the
210 server and client output from `dist/server` and `dist/client`.
211
212 ## Local dev
213
214 ```sh
215 bun alchemy dev
216 ```
217
218 `alchemy dev` runs TanStack Start's own Vite dev server (native HMR)
219 instead of deploying; `site.url` is the local address and no Railway
220 resources are created. Wrap the site in
221 `Alchemy.remote()` to deploy the live Service even during dev:
222
223 ```typescript
224 export const Website = Railway.Website.TanStackStart("Website").pipe(
225 Alchemy.remote(),
226 );
227 ```
228
229 ## Solid variant
230
231 TanStack Start's Solid flavor works the same way — swap the plugins in
232 `vite.config.ts` and keep the identical `alchemy.run.ts`:
233
234 ```typescript
235 // vite.config.ts
236 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
237 import { defineConfig } from "vite";
238 import viteSolid from "vite-plugin-solid";
239
240 export default defineConfig({
241 plugins: [tanstackStart(), viteSolid({ ssr: true })],
242 });
243 ```
244
245 `@tanstack/solid-start` exposes the same `tanstackStart()` plugin entry
246 point and the same `client`/`ssr` build environments, so the deploy is
247 identical.
248
249 ## Custom domain
250
251 ```typescript
252 const site = yield* Railway.Website.TanStackStart("Web", {
253 domain: "app.example.com",
254 });
255 ```
256
257 `domain` attaches a [`Railway.CustomDomain`](/railway/networking)
258 (`targetPort` 3000). `url` becomes `https://app.example.com`
259 instead of the generated `*.up.railway.app`.
260
261 ## Where next
262
263 - [TanStack Start API reference](/providers/railway/website/tanstackstart)
264 - [Projects](/railway/compute/projects) and
265 [Services](/railway/compute/services)
266 - [Custom domains](/railway/networking)