@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

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