@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 206 lines 6.17 KB
Raw
1 ---
2 title: TanStack Start
3 description: Deploy TanStack Start (React or Solid) to Cloudflare with Cloudflare.Website.Vite — SSR, typed Worker bindings, and HMR dev with real cloud resources.
4 sidebar:
5 order: 5
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 [TanStack Start](https://tanstack.com/start) is pure Vite —
11 `tanstackStart()` and `viteReact()` are ordinary plugins in
12 `vite.config.ts`, so
13 [`Cloudflare.Website.Vite`](/cloudflare/frontend/vite) builds the client
14 assets and the SSR server bundle in a single `vite build` pass, no
15 adapter or Wrangler config required. Support is verified: the
16 [examples/cloudflare-website-tanstack-start](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-website-tanstack-start)
17 example is checked in, and a live test deploys it in dev mode with real
18 Alchemy-managed R2 bindings.
19
20 ## Configure Vite
21
22 Your Vite config stays exactly what TanStack Start's scaffold gives
23 you — Alchemy layers its Cloudflare integration on top when it
24 builds:
25
26 ```typescript
27 // vite.config.ts
28 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
29 import viteReact from "@vitejs/plugin-react";
30 import { defineConfig } from "vite";
31
32 export default defineConfig({
33 plugins: [tanstackStart(), viteReact()],
34 });
35 ```
36
37 ## Remove `@cloudflare/vite-plugin`
38
39 :::caution[Remove @cloudflare/vite-plugin if present]
40 The TanStack CLI adds `@cloudflare/vite-plugin` to `vite.config.ts`
41 automatically when scaffolding a new app. Alchemy appends its own
42 Cloudflare Vite plugin and is **not compatible** with
43 `@cloudflare/vite-plugin` — remove it:
44
45 ```diff lang="typescript"
46 // vite.config.ts
47 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
48 import viteReact from "@vitejs/plugin-react";
49 import { defineConfig } from "vite";
50 -import { cloudflare } from "@cloudflare/vite-plugin";
51
52 export default defineConfig({
53 - plugins: [
54 - cloudflare({ viteEnvironment: { name: "ssr" } }),
55 - tanstackStart(),
56 - viteReact(),
57 - ],
58 + plugins: [tanstackStart(), viteReact()],
59 });
60 ```
61
62 :::
63
64 Also drop the dependency:
65
66 <PackageManagers remove="@cloudflare/vite-plugin" />
67
68 ## Declare the Website
69
70 Declare the site as a module-level const (rather than inline in the
71 Stack) and derive the typed shape of its bindings from it:
72
73 ```typescript
74 // alchemy.run.ts
75 import * as Alchemy from "alchemy";
76 import * as Cloudflare from "@alchemy.run/cloudflare";
77 import * as Effect from "effect/Effect";
78 import Backend, { Bucket } from "./src/backend.ts";
79
80 export const Website = Cloudflare.Website.Vite("Website", {
81 env: {
82 BUCKET: Bucket,
83 BACKEND: Backend,
84 },
85 });
86
87 export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;
88 ```
89
90 Each `env` entry becomes a native Worker binding (`BUCKET` an
91 R2 bucket, `BACKEND` a service binding to another Worker). Requests
92 matching a built client asset are served directly from the asset layer;
93 everything else (SSR routes, server routes) falls through to the
94 TanStack server handler. `WebsiteEnv` is the typed
95 shape of those bindings, derived from the declaration. The SSR server
96 bundle's Node APIs are covered by the `nodejs_compat` compatibility
97 flag, which is enabled by default for every Worker.
98
99 ## Add it to the Stack
100
101 Yield the Website from the Stack alongside anything it binds to:
102
103 ```typescript
104 // alchemy.run.ts
105 export default Alchemy.Stack(
106 "CloudflareTanstackExample",
107 {
108 providers: Cloudflare.providers(),
109 state: Cloudflare.state(),
110 },
111 Effect.gen(function* () {
112 const backend = yield* Backend;
113 const website = yield* Website;
114
115 return {
116 backendUrl: backend.url.as<string>(),
117 websiteUrl: website.url.as<string>(),
118 };
119 }),
120 );
121 ```
122
123 One Stack deploys the Backend Worker, the R2 bucket, and the TanStack
124 Start app together, and returns both URLs as stack outputs.
125
126 ## Read bindings in server code
127
128 Expose the Worker `env` through a small module so every server route
129 imports the same typed handle:
130
131 ```typescript
132 // src/env.ts
133 import * as cf from "cloudflare:workers";
134 import type { WebsiteEnv } from "../alchemy.run.ts";
135
136 // In development mode with TanStack Start, `import { env } from "cloudflare:workers"`
137 // does not work at the top level.
138 // As a workaround, we use a proxy to access the env object.
139 export const env = new Proxy({} as WebsiteEnv, {
140 get(_, prop) {
141 return cf.env[prop as keyof typeof cf.env];
142 },
143 });
144 ```
145
146 The Proxy matters: TanStack Start's dev server evaluates route modules
147 outside the Worker request context, so a top-level
148 `import { env } from "cloudflare:workers"` breaks in dev — deferring the
149 property access until a handler actually runs sidesteps it.
150
151 ## Call bindings from a route
152
153 Inside a server route handler, `env` is the standard Cloudflare runtime
154 API, fully typed:
155
156 ```typescript
157 // src/routes/api.hello.ts
158 const object = await env.BUCKET.get(key);
159
160 const res = await env.BACKEND.fetch(
161 `https://backend/?key=${encodeURIComponent(key)}`,
162 );
163 ```
164
165 `env.BACKEND` is a service binding to an Effect-native Worker — beyond
166 `fetch`, you can call its typed RPC methods directly; see
167 [Schemaless RPC](/cloudflare/apis/schemaless-rpc).
168
169 ## Deploy and dev
170
171 ```sh
172 bun alchemy deploy
173 ```
174
175 For local development:
176
177 ```sh
178 bun alchemy dev
179 ```
180
181 `alchemy dev` boots TanStack Start's Vite dev server with HMR while the
182 bindings stay attached to the **real** Alchemy-managed cloud resources —
183 this exact combination (TanStack Start dev mode + live R2 binding) is
184 covered by a live test in the Alchemy repo, so `env.BUCKET.get(key)`
185 hits the same bucket in dev as in production.
186
187 ## Solid variant
188
189 TanStack Start's Solid flavor works the same way — swap the plugins in
190 `vite.config.ts` and keep the identical `alchemy.run.ts` shape (see
191 [examples/cloudflare-tanstack-start-solid](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-tanstack-start-solid)):
192
193 ```typescript
194 // vite.config.ts
195 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
196 import { defineConfig } from "vite";
197 import viteSolid from "vite-plugin-solid";
198
199 export default defineConfig({
200 plugins: [tanstackStart(), viteSolid({ ssr: true })],
201 });
202 ```
203
204 `@tanstack/solid-start` provides the same `tanstackStart()` plugin
205 entry point, so `Cloudflare.Website.Vite` builds it identically —
206 no changes needed.