The best way to control Claude Code, Codex and more from any computer or phone
| 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. |