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

main
mdx 310 lines 8.87 KB
Raw
1 ---
2 title: Foldkit
3 description: Deploy Foldkit SPA, SSR, SSG, and hybrid applications to AWS with native local development.
4 sidebar:
5 order: 3
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `AWS.Website.Foldkit` deploys a [Foldkit](https://foldkit.dev) app to
13 AWS. It supports browser-only SPAs, server-side rendering (SSR), static site
14 generation (SSG), and hybrid rendering. Foldkit's Vite plugin generates the
15 handler and assets; Alchemy packages them for deployment.
16
17 ## Install
18
19 The build integration is not bundled with alchemy. Install
20 `@alchemy.run/frontend-frameworks`; the resource loads its `/foldkit` and
21 `/foldkit/aws` exports from your project at deploy time. It is only used at
22 build time, so a dev dependency is enough:
23
24 <PackageManagers dev={devDeps} />
25
26 ## Configure Vite
27
28 Your Vite config stays what Foldkit's setup gives you:
29
30 ```typescript
31 // vite.config.ts
32 import { foldkit } from "@foldkit/vite-plugin";
33 import { defineConfig } from "vite";
34
35 export default defineConfig({
36 plugins: [foldkit()],
37 optimizeDeps: {
38 entries: ["src/entry.ts"],
39 },
40 });
41 ```
42
43 Alchemy runs Vite programmatically on the project root, so the Foldkit
44 plugin and the rest of your setup are preserved as-is.
45
46 ## Server rendering and prerendering
47
48 Configure rendering in the application's `foldkit(...)` plugin. This example
49 uses Foldkit 0.167.0, `@foldkit/vite-plugin` 0.27.0 and compatible Effect
50 dependencies:
51
52 ```typescript
53 // vite.config.ts
54 import { foldkit } from "@foldkit/vite-plugin";
55 import { defineConfig } from "vite";
56
57 export default defineConfig({
58 plugins: [
59 foldkit({
60 ssr: {
61 serverEntry: "/src/entry.server.ts",
62 clientEntry: "/src/entry.ts",
63 build: true,
64 },
65 }),
66 ],
67 });
68 ```
69
70 The server entry exports `renderPage` and `renderDocument`. Import stylesheets
71 from the client entry and use `Runtime.hydrate` to start the browser application.
72 Remove the source `index.html` for this build: Foldkit generates the complete
73 HTML document, including the client script, stylesheets and module preload links.
74
75 ```typescript
76 // src/entry.server.ts
77 import { Server } from "foldkit/experimental";
78
79 export const renderDocument = Server.renderDocument;
80 ```
81
82 Keep your application's `renderPage` export alongside the document renderer.
83 Foldkit currently exposes its server rendering API through `foldkit/experimental`;
84 see its [server rendering guide](https://foldkit.dev/core/server-rendering) for
85 the application and hydration contract.
86
87 For static site generation (SSG), change `build` to `{ prerender: true }` and
88 export the URLs to generate from the server entry:
89
90 ```typescript
91 // src/entry.server.ts
92 export const prerenderPaths = ["/", "/about"];
93 ```
94
95 SSG renders those URLs during the build. SSR renders a page when its request
96 arrives. A hybrid application prerenders some URLs and renders others on request.
97 The same `renderPage` and `renderDocument` exports serve both delivery policies.
98
99 AWS chooses its deployment resources before building. Keep the default for a
100 browser-only SPA; select `output: "server"` for request-time rendering:
101
102 ```typescript
103 // alchemy.run.ts
104 export const Website = AWS.Website.Foldkit("Website", {
105 output: "server",
106 });
107 ```
108
109 CloudFront serves assets and prerendered pages from S3. Requests that match no
110 file, and methods other than GET or HEAD, reach the server: a Lambda Web
111 Function by default, or a Lambda Function with `server: "function"`. The
112 application owns its response status and headers through `renderPage`.
113
114 For static-only SSG, deploy the prerendered client output without a server:
115
116 ```typescript
117 // alchemy.run.ts
118 export const Website = AWS.Website.Foldkit("Website", {
119 output: "static",
120 errorPage: "404.html",
121 });
122 ```
123
124 Supply `public/404.html` for this example. URLs that were not generated return
125 404; browser interaction still works through hydration. `output: "server"`
126 retains the handler even when all known pages were prerendered. A server build
127 with no `output` choice fails rather than discarding its handler.
128 `spa` and `errorPage` apply only to assets-only deployments.
129
130 ## Declare the Website
131
132 Declare the site as a module-level const (rather than inline in the
133 Stack):
134
135 ```typescript
136 // alchemy.run.ts
137 import * as AWS from "@alchemy.run/aws";
138
139 export const Website = AWS.Website.Foldkit("Website");
140 ```
141
142 For an app in a subdirectory of a monorepo, point `rootDir` at it:
143
144 ```typescript
145 export const Website = AWS.Website.Foldkit("Website", {
146 rootDir: "applications/web",
147 });
148 ```
149
150 ## Add it to the Stack
151
152 Yield the site from your Stack and return its URL:
153
154 ```typescript
155 // alchemy.run.ts
156 import * as Alchemy from "alchemy";
157 import * as Effect from "effect/Effect";
158
159 export default Alchemy.Stack(
160 "MyFoldkitSite",
161 {
162 providers: AWS.providers(),
163 state: AWS.state(),
164 },
165 Effect.gen(function* () {
166 const site = yield* Website;
167 return { url: site.url };
168 }),
169 );
170 ```
171
172 One declaration expands into the whole stack — an S3 bucket, the asset
173 upload, a CloudFront KeyValueStore holding the file manifest, a
174 viewer-request CloudFront Function, and the distribution itself.
175
176 ```sh
177 bun alchemy deploy
178 ```
179
180 ## Deep links
181
182 A browser-only Foldkit app that uses URL routing (`Runtime.makeApplication` with
183 `routing`, `onUrlRequest`, and `onUrlChange`) resolves routes on the
184 client, so a deep link like `/counter/42` arrives at the edge as a
185 request for a file that does not exist.
186
187 `Foldkit` sets `spa` by default, which answers those misses with
188 `index.html` and a `200` — the Foldkit runtime resolves the route once
189 the app boots.
190
191 An app that ships a real 404 page opts out with `errorPage`. The two are
192 mutually exclusive:
193
194 ```typescript
195 export const Website = AWS.Website.Foldkit("Website", {
196 spa: false,
197 errorPage: "404.html",
198 });
199 ```
200
201 ## Add environment variables
202
203 Set server environment variables through `env` when deploying a server build:
204
205 ```typescript
206 // alchemy.run.ts
207 export const Website = AWS.Website.Foldkit("Website", {
208 output: "server",
209 env: { API_BASE: "https://api.example.com" },
210 });
211 ```
212
213 Server code reads these values from `process.env`. Alchemy applies them to the
214 native dev server under `alchemy dev` and to the server on deploy.
215
216 An Output from another resource can be passed inside the Stack generator:
217
218 ```typescript
219 Effect.gen(function* () {
220 const api = yield* Api;
221 const site = yield* AWS.Website.Foldkit("Website", {
222 output: "server",
223 env: { API_BASE: api.url },
224 });
225 return { url: site.url };
226 });
227 ```
228
229 ## Read the environment in client code
230
231 Vite inlines `VITE_*` values as `import.meta.env.VITE_*` during the build.
232 Set browser configuration in the app's `.env` file or the deployment environment:
233
234 ```sh
235 # .env
236 VITE_API_URL=https://api.example.com
237 ```
238
239 ```typescript
240 const apiUrl = import.meta.env.VITE_API_URL;
241 ```
242
243 Values forwarded through `env` are also available to the build. A `VITE_*` key
244 becomes public browser configuration; keep credentials in unprefixed server
245 variables. Values serialized into Foldkit Flags also reach the browser.
246
247 ## Build configuration
248
249 Vite configuration — the Foldkit plugin included — lives in your
250 project's own `vite.config.*`. The `vite` bag is for deploy-time
251 overrides merged *over* that file, for values decided by the
252 deployment (config files can't consume alchemy `Output`s):
253
254 ```typescript
255 export const Website = AWS.Website.Foldkit("Docs", {
256 vite: {
257 outDir: "build",
258 },
259 });
260 ```
261
262 `outDir` is relative to `rootDir`. For server builds, Alchemy places client and
263 server outputs under `client/` and `server/` in this directory. Without an
264 override, the app's resolved output directories are used. `config` selects an
265 alternate Vite configuration file relative to `rootDir`.
266
267 ## Local dev
268
269 `alchemy dev` runs the app's own Vite dev server, so Foldkit's
270 state-preserving live reload and its devtools wiring work unchanged. `site.url` is
271 the local address and no AWS resources are created. Wrap the site in
272 `Alchemy.remote()` to deploy the real infrastructure even during dev.
273
274 Pin the dev server's address when several apps run in one Stack:
275
276 ```typescript
277 export const Website = AWS.Website.Foldkit("Website", {
278 dev: { host: "127.0.0.1", port: 5180, strictPort: true },
279 });
280 ```
281
282 ## Custom domain
283
284 ```typescript
285 // alchemy.run.ts
286 export const Website = AWS.Website.Foldkit("Website", {
287 domain: { name: "app.example.com" },
288 });
289 ```
290
291 The hosted zone is inferred from the hostname. Pass `hostedZoneId` to
292 pin it when several zones could match.
293
294 Serve several sites under one distribution by pointing `domain.router`
295 at an existing
296 [`AWS.Website.Router`](/aws/frontend/static-site#compose-sites-with-a-router).
297 The site takes the Router's outputs, so both are yielded inside the
298 Stack generator:
299
300 ```typescript
301 Effect.gen(function* () {
302 const router = yield* AWS.Website.Router("Router", {});
303
304 const site = yield* AWS.Website.Foldkit("Website", {
305 domain: { router, name: "app.example.com" },
306 });
307
308 return { url: site.url };
309 });
310 ```