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

main
mdx 270 lines 7.67 KB
Raw
1 ---
2 title: TanStack Start
3 description: Deploy TanStack Start (React or Solid) to Hetzner with Hetzner.Website.TanStackStart — SSR as a systemd unit on port 3000, client assets baked into the unit, 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 `Hetzner.Website.TanStackStart` deploys a
13 [TanStack Start](https://tanstack.com/start) app to a Hetzner Cloud
14 Server. TanStack Start is pure Vite, so Alchemy runs your project's own
15 `vite 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 `/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 Hetzner 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 Hetzner from "@alchemy.run/hetzner";
85
86 export const Website = Hetzner.Website.TanStackStart("Website");
87 ```
88
89 Pass `server` to host the site on an existing
90 [`Hetzner.Server`](/hetzner/compute/servers) — several sites and
91 APIs can share one box. `rootDir` is the project root — the directory
92 holding `package.json` and `vite.config.*`. It defaults to `"."`, so
93 set it only when the app does not sit next to `alchemy.run.ts`:
94
95 ```typescript
96 export const Website = Hetzner.Website.TanStackStart("Website", {
97 rootDir: "./app",
98 });
99 ```
100
101 ## Add it to the Stack
102
103 Yield the site from your Stack and return its URL:
104
105 ```typescript
106 // alchemy.run.ts
107 import * as Alchemy from "alchemy";
108 import * as Effect from "effect/Effect";
109
110 export default Alchemy.Stack(
111 "MyTanStackSite",
112 {
113 providers: Hetzner.providers(),
114 state: Alchemy.localState(),
115 },
116 Effect.gen(function* () {
117 const site = yield* Website;
118 return { url: site.url };
119 }),
120 );
121 ```
122
123 Requests matching a built client asset are served first; everything
124 else — SSR routes, server routes, server functions — falls through to
125 the Node handler on the Server.
126
127 The live `url` is `http://{ipv4}:3000`. `site.server` and
128 `site.service` are the Hetzner resources underneath — `undefined`
129 during `alchemy dev`.
130
131 See the
132 [TanStack Start API reference](/providers/hetzner/website/tanstackstart)
133 for every prop and attribute.
134
135 ## Add environment variables
136
137 Process environment is a top-level `env` map — plain strings, or
138 `Redacted` values:
139
140 ```diff lang="typescript"
141 // alchemy.run.ts
142 export const Website = Hetzner.Website.TanStackStart("Website", {
143 + env: {
144 + API_BASE: "https://api.example.com",
145 + },
146 });
147 ```
148
149 The values are copied onto `process.env` before the build and the
150 dev server, and onto the systemd unit at deploy time, so server
151 code reads the same keys in both modes. Client inlining is whatever
152 Vite does (`VITE_` prefixes).
153
154 An output from another resource only exists once that resource is
155 yielded, so declare the site inside the Stack generator instead:
156
157 ```typescript
158 // alchemy.run.ts
159 Effect.gen(function* () {
160 const api = yield* Api;
161
162 const site = yield* Hetzner.Website.TanStackStart("Website", {
163 env: { API_BASE: api.url },
164 });
165
166 return { url: site.url };
167 });
168 ```
169
170 ## Read the environment in a server function
171
172 The TanStack Start server is a plain Node process, so server
173 functions read the environment from `process.env`:
174
175 ```typescript
176 // src/routes/index.tsx
177 import { createServerFn } from "@tanstack/react-start";
178
179 const getApiBase = createServerFn({ method: "GET" }).handler(() => ({
180 apiBase: process.env.API_BASE ?? "unset",
181 }));
182 ```
183
184 Values prefixed `VITE_` are inlined into the client bundle at build time
185 instead, as `import.meta.env.VITE_*` — set those in the shell that runs
186 `alchemy deploy`, not in `env`.
187
188 ## Read the environment in a server route
189
190 Server routes run on the same Node process and read `process.env` the
191 same way:
192
193 ```typescript
194 // src/routes/api.hello.ts
195 import { createFileRoute } from "@tanstack/react-router";
196
197 export const Route = createFileRoute("/api/hello")({
198 server: {
199 handlers: {
200 GET: () => new Response(process.env.API_BASE ?? "unset"),
201 },
202 },
203 });
204 ```
205
206 ## Build configuration
207
208 The build runs through your project's own `vite.config.ts` — the
209 `tanstackStart()` plugin and everything else in it apply as-is. Keep
210 vite's default `build.outDir` (`dist`); the integration reads the
211 server and client output from `dist/server` and `dist/client`.
212
213 ## Local dev
214
215 ```sh
216 bun alchemy dev
217 ```
218
219 `alchemy dev` runs TanStack Start's own Vite dev server (native HMR)
220 instead of deploying; `site.url` is the local address and no Hetzner
221 resources are created. Wrap the site in `Alchemy.remote()` to deploy
222 the live Server and Service even during dev:
223
224 ```typescript
225 export const Website = Hetzner.Website.TanStackStart("Website").pipe(
226 Alchemy.remote(),
227 );
228 ```
229
230 ## Solid variant
231
232 TanStack Start's Solid flavor works the same way — swap the plugins in
233 `vite.config.ts` and keep the identical `alchemy.run.ts`:
234
235 ```typescript
236 // vite.config.ts
237 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
238 import { defineConfig } from "vite";
239 import viteSolid from "vite-plugin-solid";
240
241 export default defineConfig({
242 plugins: [tanstackStart(), viteSolid({ ssr: true })],
243 });
244 ```
245
246 `@tanstack/solid-start` exposes the same `tanstackStart()` plugin entry
247 point and the same `client`/`ssr` build environments, so the deploy is
248 identical.
249
250 ## Custom domain
251
252 ```typescript
253 const zone = yield* Hetzner.Zone("dns", { name: "example.com" });
254 const site = yield* Hetzner.Website.TanStackStart("Web", {
255 domain: "app.example.com",
256 zone,
257 });
258 ```
259
260 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
261 — the Website does not create one. It adds an A record pointing at
262 the Server's public IPv4. `url` becomes `http://app.example.com:3000`.
263 There is no TLS on the Service.
264
265 ## Where next
266
267 - [TanStack Start API reference](/providers/hetzner/website/tanstackstart)
268 - [Servers](/hetzner/compute/servers) and
269 [Services](/hetzner/compute/services)
270 - [DNS](/hetzner/networking/dns)