@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 319 lines 8.76 KB
Raw
1 ---
2 title: TanStack Start
3 description: Deploy TanStack Start (React or Solid) to AWS with AWS.Website.TanStackStart — SSR on a Lambda Web Function, client assets on S3 + CloudFront, 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 `AWS.Website.TanStackStart` deploys a
13 [TanStack Start](https://tanstack.com/start) app to AWS. TanStack Start
14 is pure Vite, so Alchemy runs your project's own `vite build`: the SSR
15 server runs on a [Lambda Web Function](/aws/compute/web-functions) and
16 streams its responses, and client assets are served from a private S3
17 bucket through CloudFront. A CloudFront Function routes each request at
18 the edge — uploaded files go to S3, everything else streams from the
19 server.
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 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 ## Configure Vite
32
33 Your `vite.config.ts` stays exactly what TanStack Start's scaffold gives
34 you — no adapter, no deployment preset:
35
36 ```typescript
37 // vite.config.ts
38 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
39 import viteReact from "@vitejs/plugin-react";
40 import { defineConfig } from "vite";
41
42 export default defineConfig({
43 plugins: [tanstackStart(), viteReact()],
44 });
45 ```
46
47 Alchemy drives that config's `builder.buildApp()` and forces the SSR
48 bundle to be self-contained, then serves its fetch handler from a Node
49 server.
50
51 :::caution[Remove @cloudflare/vite-plugin if present]
52 The TanStack CLI adds `@cloudflare/vite-plugin` when scaffolding a new
53 app. It builds for workerd, not Node, so an AWS deploy needs it gone:
54
55 ```diff lang="typescript"
56 // vite.config.ts
57 -import { cloudflare } from "@cloudflare/vite-plugin";
58 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
59 import viteReact from "@vitejs/plugin-react";
60 import { defineConfig } from "vite";
61
62 export default defineConfig({
63 - plugins: [
64 - cloudflare({ viteEnvironment: { name: "ssr" } }),
65 - tanstackStart(),
66 - viteReact(),
67 - ],
68 + plugins: [tanstackStart(), viteReact()],
69 });
70 ```
71
72 :::
73
74 ## Declare the Website
75
76 Declare the site as a module-level const (rather than inline in the
77 Stack):
78
79 ```typescript
80 // alchemy.run.ts
81 import * as AWS from "@alchemy.run/aws";
82
83 export const Website = AWS.Website.TanStackStart("Website");
84 ```
85
86 `rootDir` is the project root — the directory holding `package.json`
87 and `vite.config.*`. It defaults to `"."`, so set it only when the app
88 does not sit next to `alchemy.run.ts`:
89
90 ```typescript
91 export const Website = AWS.Website.TanStackStart("Website", {
92 rootDir: "./app",
93 });
94 ```
95
96 ## Add it to the Stack
97
98 Yield the site from your Stack and return its URL:
99
100 ```typescript
101 // alchemy.run.ts
102 import * as Alchemy from "alchemy";
103 import * as Effect from "effect/Effect";
104
105 export default Alchemy.Stack(
106 "MyTanStackSite",
107 {
108 providers: AWS.providers(),
109 state: AWS.state(),
110 },
111 Effect.gen(function* () {
112 const site = yield* Website;
113 return { url: site.url };
114 }),
115 );
116 ```
117
118 Requests matching a built client asset are served straight from S3;
119 everything else — SSR routes, server routes, server functions — falls
120 through to the server.
121
122 ## Add environment variables
123
124 The server function's environment is configured under `env`:
125
126 ```diff lang="typescript"
127 // alchemy.run.ts
128 export const Website = AWS.Website.TanStackStart("Website", {
129 + env: {
130 + API_BASE: "https://api.example.com",
131 + },
132 });
133 ```
134
135 `env` values are set on the server on deploy and injected into
136 the dev server's process environment under `alchemy dev`, so server code
137 reads the same values in both modes. Sibling props tune the
138 server itself (`timeout`, `maxConcurrencyPerEnvironment`,
139 `maxEnvironments`).
140
141 An output from another resource only exists once that resource is
142 yielded, so declare the site inside the Stack generator instead:
143
144 ```typescript
145 // alchemy.run.ts
146 Effect.gen(function* () {
147 const api = yield* Api;
148
149 const site = yield* AWS.Website.TanStackStart("Website", {
150 env: { API_BASE: api.url },
151 });
152
153 return { url: site.url };
154 });
155 ```
156
157 ## Read the environment in a server function
158
159 The TanStack Start server is a plain Node server, so server
160 functions read the environment from `process.env`:
161
162 ```typescript
163 // src/routes/index.tsx
164 import { createServerFn } from "@tanstack/react-start";
165
166 const getApiBase = createServerFn({ method: "GET" }).handler(() => ({
167 apiBase: process.env.API_BASE ?? "unset",
168 }));
169 ```
170
171 Values prefixed `VITE_` are inlined into the client bundle at build time
172 instead, as `import.meta.env.VITE_*` — set those in the shell that runs
173 `alchemy deploy`, not in `env`.
174
175 ## Read the environment in a server route
176
177 Server routes run on the same server and read `process.env` the same
178 way:
179
180 ```typescript
181 // src/routes/api.hello.ts
182 import { createFileRoute } from "@tanstack/react-router";
183
184 export const Route = createFileRoute("/api/hello")({
185 server: {
186 handlers: {
187 GET: () => new Response(process.env.API_BASE ?? "unset"),
188 },
189 },
190 });
191 ```
192
193 ## Call AWS services from server code
194
195 The composite creates and owns the server Lambda's execution role, and
196 exposes no prop to add permissions to it. Server code that needs to
197 reach AWS goes behind its own Lambda, where capabilities are bound
198 explicitly:
199
200 ```typescript
201 // alchemy.run.ts
202 Effect.gen(function* () {
203 const api = yield* Api;
204
205 const site = yield* AWS.Website.TanStackStart("Website", {
206 env: { API_BASE: api.url },
207 });
208
209 return { url: site.url };
210 });
211 ```
212
213 A server function then calls that API over HTTP with the URL it was
214 handed:
215
216 ```typescript
217 // src/routes/index.tsx
218 import { createServerFn } from "@tanstack/react-start";
219
220 const readObject = createServerFn({ method: "GET" }).handler(async () => {
221 const res = await fetch(`${process.env.API_BASE}/hello`);
222 return { body: await res.text() };
223 });
224 ```
225
226 See [Effect HTTP API](/aws/apis/effect-http-api) for building that
227 Lambda and binding it to the resources it reads.
228
229 ## Build configuration
230
231 The build runs through your project's own `vite.config.ts` — the
232 `tanstackStart()` plugin and everything else in it apply as-is. Keep
233 vite's default `build.outDir` (`dist`); the integration reads the
234 server and client output from `dist/server` and `dist/client`.
235
236 ## Run on a Lambda Function
237
238 Web Functions run in a subset of Regions. Elsewhere, set
239 `server: "function"`: the app builds with the `/tanstack-start/aws` deploy target
240 and runs on a Lambda Function behind a streaming Function URL, tuned with
241 `memorySize`, `architecture`, and `runtime`:
242
243 ```diff lang="typescript"
244 // alchemy.run.ts
245 export const Website = AWS.Website.TanStackStart("Website", {
246 + server: "function",
247 + memorySize: 2048,
248 });
249 ```
250
251 ## Local dev
252
253 ```sh
254 bun alchemy dev
255 ```
256
257 `alchemy dev` runs TanStack Start's own Vite dev server (native HMR)
258 instead of deploying anything; `site.url` is the dev server's
259 `http://localhost:<port>` address and no AWS resources are created. Wrap
260 the site in `Alchemy.remote()` to deploy the real infrastructure even
261 during dev.
262
263 ## Solid variant
264
265 TanStack Start's Solid flavor works the same way — swap the plugins in
266 `vite.config.ts` and keep the identical `alchemy.run.ts`:
267
268 ```typescript
269 // vite.config.ts
270 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
271 import { defineConfig } from "vite";
272 import viteSolid from "vite-plugin-solid";
273
274 export default defineConfig({
275 plugins: [tanstackStart(), viteSolid({ ssr: true })],
276 });
277 ```
278
279 `@tanstack/solid-start` exposes the same `tanstackStart()` plugin entry
280 point and the same `client`/`ssr` build environments, so the deploy is
281 identical.
282
283 ## Custom domain
284
285 ```typescript
286 // alchemy.run.ts
287 export const Website = AWS.Website.TanStackStart("Website", {
288 domain: { name: "app.example.com" },
289 });
290 ```
291
292 The certificate is created in `us-east-1` (required by CloudFront), DNS
293 validation records and the alias record are managed through Route 53.
294 The hosted zone is inferred from the hostname — pass `hostedZoneId` to
295 pin it when several zones could match.
296
297 ## Share a distribution with Router
298
299 CloudFront distributions take minutes to create. To serve several sites
300 (or a site plus an API) from one distribution, attach the site to an
301 [`AWS.Website.Router`](/aws/frontend/static-site#compose-sites-with-a-router):
302
303 The site takes the Router's outputs, so both are yielded inside the
304 Stack generator:
305
306 ```typescript
307 // alchemy.run.ts
308 Effect.gen(function* () {
309 const router = yield* AWS.Website.Router("FrontDoor", {
310 domain: { name: "example.com" },
311 });
312
313 const site = yield* AWS.Website.TanStackStart("Website", {
314 domain: { router },
315 });
316
317 return { url: site.url };
318 });
319 ```