@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 309 lines 10.3 KB
Raw
1 ---
2 title: Foldkit
3 description: Deploy Foldkit SPA, SSR, SSG, and hybrid applications to Cloudflare Workers.
4 sidebar:
5 order: 8
6 ---
7
8 `Cloudflare.Website.Foldkit` deploys a [Foldkit](https://foldkit.dev) app
9 as a Cloudflare Worker. Alchemy runs the project's Vite build and uploads
10 the client output as Worker static assets. With `ssr.build` enabled, the
11 generated Fetch handler becomes the Worker entry.
12
13 Configure rendering in the application's Foldkit plugin. The resource supports
14 browser-only SPAs, server-side rendering (SSR), static site generation (SSG),
15 and hybrid rendering. Asset routing follows the build's output.
16
17 ## Configure Vite
18
19 Keep the `foldkit()` plugin from the Foldkit scaffold and your normal Vite
20 plugins:
21
22 ```typescript
23 // vite.config.ts
24 import { foldkit } from "@foldkit/vite-plugin";
25 import { defineConfig } from "vite";
26
27 export default defineConfig({
28 plugins: [foldkit()],
29 });
30 ```
31
32 Alchemy runs Vite programmatically on the project root and layers
33 its Cloudflare integration on top of this config — the Foldkit
34 plugin and the rest of your setup are preserved as-is. This is a
35 client-only app: a plain `vite build`, deployed as assets.
36
37 ### Server rendering and prerendering
38
39 Configure rendering in the application's `foldkit(...)` plugin. This example
40 uses Foldkit 0.167.0, `@foldkit/vite-plugin` 0.27.0 and compatible Effect
41 dependencies:
42
43 ```typescript
44 // vite.config.ts
45 import { foldkit } from "@foldkit/vite-plugin";
46 import { defineConfig } from "vite";
47
48 export default defineConfig({
49 plugins: [
50 foldkit({
51 ssr: {
52 serverEntry: "/src/entry.server.ts",
53 clientEntry: "/src/entry.ts",
54 build: true,
55 },
56 }),
57 ],
58 });
59 ```
60
61 The server entry exports `renderPage` and `renderDocument`. Import stylesheets
62 from the client entry and use `Runtime.hydrate` to start the browser application.
63 Remove the source `index.html` for this build: Foldkit generates the complete
64 HTML document, including the client script, stylesheets and module preload links.
65
66 ```typescript
67 // src/entry.server.ts
68 import { Server } from "foldkit/experimental";
69
70 export const renderDocument = Server.renderDocument;
71 ```
72
73 Keep your application's `renderPage` export alongside the document renderer.
74 Foldkit currently exposes its server rendering API through `foldkit/experimental`;
75 see its [server rendering guide](https://foldkit.dev/core/server-rendering) for
76 the application and hydration contract.
77
78 For static site generation (SSG), change `build` to `{ prerender: true }` and
79 export the URLs to generate from the server entry:
80
81 ```typescript
82 // src/entry.server.ts
83 export const prerenderPaths = ["/", "/about"];
84 ```
85
86 SSG renders those URLs during the build. SSR renders a page when its request
87 arrives. A hybrid application prerenders some URLs and renders others on request.
88 The same `renderPage` and `renderDocument` exports serve both delivery policies.
89
90 The same Website declaration deploys the generated handler and client assets.
91 Prerendered pages are served as files. Requests that match no file reach the
92 handler, where `renderPage` chooses whether to render a page, redirect or return
93 404. For an SSG-only application, return 404 for URLs outside its generated
94 route set. Rendering those URLs on request makes the deployment hybrid.
95
96 Foldkit generates the shared client/server build identity automatically.
97
98 ## Declare the Website
99
100 Declare the site as a module-level const (rather than inline in the
101 Stack) and derive the typed shape of its bindings from it:
102
103 ```typescript
104 // alchemy.run.ts
105 import * as Cloudflare from "@alchemy.run/cloudflare";
106
107 export const Website = Cloudflare.Website.Foldkit("Foldkit");
108
109 export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;
110 ```
111
112 `WebsiteEnv` is the typed shape of the Worker's bindings. A client-only app
113 with a custom Worker imports it in [Custom Worker entry](#custom-worker-entry).
114
115 For an app in a subdirectory of a monorepo, point `rootDir` at it:
116
117 ```typescript
118 export const Website = Cloudflare.Website.Foldkit("Foldkit", {
119 rootDir: "applications/web",
120 });
121 ```
122
123 ## Add it to the Stack
124
125 Yield the Website Effect from your Stack and return its URL — see
126 [examples/cloudflare-foldkit-spa](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-foldkit-spa)
127 for the client-only shape and
128 [examples/cloudflare-foldkit-ssr](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-foldkit-ssr)
129 for the server-rendered one:
130
131 ```typescript
132 // alchemy.run.ts
133 import * as Alchemy from "alchemy";
134 import * as Effect from "effect/Effect";
135
136 export default Alchemy.Stack(
137 "CloudflareFoldkitExample",
138 {
139 providers: Cloudflare.providers(),
140 state: Cloudflare.state(),
141 },
142 Effect.gen(function* () {
143 const worker = yield* Website;
144
145 return {
146 url: worker.url,
147 };
148 }),
149 );
150 ```
151
152 ## Asset routing
153
154 GET and HEAD requests serve matching client assets and prerendered pages first.
155 The browser build contains a rendered homepage only when `/` was prerendered;
156 otherwise the homepage reaches the handler. Other application methods reach
157 the Worker rather than a prerendered file.
158
159 Browser-only builds use `notFoundHandling: "single-page-application"`. An
160 unmatched path serves `index.html`, and the browser router resolves the URL.
161 Server builds use normal asset lookup and send misses to Foldkit's handler.
162
163 Explicit `assets` settings override these defaults. An application that
164 ships a real 404 page opts out of the fallback:
165
166 ```typescript
167 export const Website = Cloudflare.Website.Foldkit("Foldkit", {
168 assets: {
169 notFoundHandling: "404-page",
170 },
171 });
172 ```
173
174 ## Add environment variables
175
176 Pass browser configuration through `VITE_`-prefixed keys in `env`. Alchemy
177 inlines these values into `import.meta.env.*` during the Vite build:
178
179 ```diff lang="typescript"
180 // alchemy.run.ts
181 export const Website = Cloudflare.Website.Foldkit("Foldkit", {
182 + env: {
183 + VITE_API_URL: backend.url.as<string>(),
184 + },
185 });
186 ```
187
188 ## Read the environment in client code
189
190 Type a custom public key with Vite's standard `ImportMetaEnv` augmentation:
191
192 ```typescript
193 // src/vite-env.d.ts
194 /// <reference types="vite/client" />
195
196 interface ImportMetaEnv {
197 readonly VITE_API_URL: string;
198 }
199 ```
200
201 Client code reads it as `import.meta.env.VITE_API_URL`. See
202 [Environment](/cloudflare/frontend/vite#environment) for the full
203 inlining semantics.
204
205 The same `env` prop carries runtime bindings, including KV namespaces, secrets
206 and other Workers. A custom Worker reads them from its `env` argument. Keep
207 secrets out of `VITE_*` keys and serialized Foldkit Flags; both reach the browser.
208
209 ## Custom Worker entry
210
211 A client-only app that must also do something at the edge — serve an
212 API route, wrap the app in error reporting, export Durable Object
213 classes — points `main` at its own module. The module builds through
214 Vite's `ssr` environment and becomes the deployed Worker entry. The
215 client build is still reachable through the Worker's `ASSETS`
216 binding, so the Worker answers its own routes and hands everything
217 else back to the asset layer:
218
219 ```typescript
220 // src/worker.ts
221 import type { WebsiteEnv } from "../alchemy.run.ts";
222
223 export default {
224 async fetch(request: Request, env: WebsiteEnv): Promise<Response> {
225 const url = new URL(request.url);
226
227 if (url.pathname === "/api/ticker") {
228 const body = await env.TICKER.get("ticker:clubs");
229 return new Response(body, {
230 headers: { "content-type": "application/json" },
231 });
232 }
233
234 return env.ASSETS.fetch(request);
235 },
236 };
237 ```
238
239 Your `vite.config.ts` needs no changes — the injected Cloudflare
240 plugin points the `ssr` environment at `main` itself. Just declare
241 the entry and bind what the Worker needs:
242
243 ```typescript
244 // alchemy.run.ts
245 export const Ticker = Cloudflare.KV.Namespace("Ticker");
246
247 export const Website = Cloudflare.Website.Foldkit("Foldkit", {
248 main: "src/worker.ts",
249 env: { TICKER: Ticker },
250 assets: {
251 runWorkerFirst: ["/api/*"],
252 },
253 });
254 ```
255
256 `runWorkerFirst` sends `/api/*` to the Worker ahead of the asset
257 layer. The client-only fallback is still derived — a deep link the
258 Worker hands back through `env.ASSETS.fetch` is answered with the
259 template as before.
260
261 `env.TICKER` is typed as a KV namespace, and Alchemy supplies the `ASSETS`
262 binding. These runtime bindings are available to Worker code; browser code
263 receives only the public build-time values.
264
265 A server-rendered or prerendered app cannot take a `main`: with
266 `ssr.build` set, Foldkit's plugin owns the server entry, and the
267 build fails if another module claims it. Handle page redirects, status and
268 response headers in `renderPage`. Put data APIs or additional Worker handlers in a separate Worker.
269
270 ## Local dev
271
272 ```sh
273 bun alchemy dev
274 ```
275
276 `alchemy dev` runs Foldkit's native Vite dev server with state-preserving live
277 reload and devtools. SSR uses the same server entry as the production build.
278 A development reload restores the Model and rebuilds the DOM; refresh manually
279 to exercise hydration from the server-rendered HTML.
280
281 A client-only app with a custom `main` runs its Worker through workerd and can
282 use Cloudflare bindings. The native Foldkit SSR dev host runs in Node; it does
283 not expose the generated Worker's bindings as an `env` argument to `renderPage`.
284
285 Pin the dev server's address when several apps run in one Stack:
286
287 ```typescript
288 export const Website = Cloudflare.Website.Foldkit("Foldkit", {
289 dev: { host: "127.0.0.1", port: 5180, strictPort: true },
290 });
291 ```
292
293 ## Where next
294
295 - [The Vite resource](/cloudflare/frontend/vite) — build model, env
296 inlining, runtime bindings, memo, dev mode.
297 - [SPA / CSR example](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-foldkit-spa)
298 — the generated browser-only counter.
299 - [SSG example](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-foldkit-ssg)
300 — prerendered home and about pages with hydration.
301 - [SSR example](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-foldkit-ssr)
302 — the generated cookie-backed counter, rendered per request.
303 - [Hybrid example](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-foldkit-hybrid)
304 — prerendered pages and a request-rendered counter in one application.
305 - [Foldkit server rendering](https://foldkit.dev/core/server-rendering)
306 — the hydration contract, automatic build identity, `ssr.build`, and
307 `foldkit.build.json`.
308 - [Frontend overview](/cloudflare/frontend/frontends) — the rest of
309 the Cloudflare frontend family.