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

main
mdx 255 lines 7.7 KB
Raw
1 ---
2 title: Foldkit
3 description: Deploy Foldkit SPA, SSR, SSG, and hybrid applications to Hetzner with native local development.
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 `Hetzner.Website.Foldkit` deploys a [Foldkit](https://foldkit.dev) app to
13 Hetzner. 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`
21 and `/foldkit/node` exports from your project at deploy time. It is only
22 used at 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. Vite plugins
29 like Tailwind go in `plugins` as usual:
30
31 ```typescript
32 // vite.config.ts
33 import { foldkit } from "@foldkit/vite-plugin";
34 import tailwindcss from "@tailwindcss/vite";
35 import { defineConfig } from "vite";
36
37 export default defineConfig({
38 plugins: [foldkit(), tailwindcss()],
39 optimizeDeps: {
40 entries: ["src/entry.ts"],
41 },
42 });
43 ```
44
45 Alchemy runs Vite programmatically on the project root. The Foldkit
46 plugin and the rest of your setup are preserved as-is.
47
48 ## Server rendering and prerendering
49
50 Configure rendering in the application's `foldkit(...)` plugin. This example
51 uses Foldkit 0.167.0, `@foldkit/vite-plugin` 0.27.0 and compatible Effect
52 dependencies:
53
54 ```typescript
55 // vite.config.ts
56 import { foldkit } from "@foldkit/vite-plugin";
57 import { defineConfig } from "vite";
58
59 export default defineConfig({
60 plugins: [
61 foldkit({
62 ssr: {
63 serverEntry: "/src/entry.server.ts",
64 clientEntry: "/src/entry.ts",
65 build: true,
66 },
67 }),
68 ],
69 });
70 ```
71
72 The server entry exports `renderPage` and `renderDocument`. Import stylesheets
73 from the client entry and use `Runtime.hydrate` to start the browser application.
74 Remove the source `index.html` for this build: Foldkit generates the complete
75 HTML document, including the client script, stylesheets and module preload links.
76
77 ```typescript
78 // src/entry.server.ts
79 import { Server } from "foldkit/experimental";
80
81 export const renderDocument = Server.renderDocument;
82 ```
83
84 Keep your application's `renderPage` export alongside the document renderer.
85 Foldkit currently exposes its server rendering API through `foldkit/experimental`;
86 see its [server rendering guide](https://foldkit.dev/core/server-rendering) for
87 the application and hydration contract.
88
89 For static site generation (SSG), change `build` to `{ prerender: true }` and
90 export the URLs to generate from the server entry:
91
92 ```typescript
93 // src/entry.server.ts
94 export const prerenderPaths = ["/", "/about"];
95 ```
96
97 SSG renders those URLs during the build. SSR renders a page when its request
98 arrives. A hybrid application prerenders some URLs and renders others on request.
99 The same `renderPage` and `renderDocument` exports serve both delivery policies.
100
101 The same Website declaration deploys the client assets and generated handler.
102 GET and HEAD requests serve matching assets and prerendered pages first;
103 remaining requests go to the handler. Other methods bypass static assets.
104 The application owns its response status and headers through `renderPage`.
105 For an SSG-only application, return 404 for URLs outside its generated route set;
106 allowing those URLs to render on request makes the deployment hybrid.
107
108 Browser-only builds use SPA fallback. Server builds send unmatched requests to
109 the handler. Explicit `assets.notFoundHandling` settings override these defaults.
110
111 Vite's resolved `base` also mounts the client assets. With `base: "/app/"`,
112 `/app/assets/main.js` serves `assets/main.js` from the client output. SPA fallback
113 is limited to that prefix; server handlers receive the original URL.
114
115 ## Declare the Website
116
117 Declare the site as a module-level const (rather than inline in the
118 Stack):
119
120 ```typescript
121 // alchemy.run.ts
122 import * as Hetzner from "@alchemy.run/hetzner";
123
124 export const Website = Hetzner.Website.Foldkit("Website");
125 ```
126
127 For an app in a subdirectory of a monorepo, point `rootDir` at it:
128
129 ```typescript
130 export const Website = Hetzner.Website.Foldkit("Website", {
131 rootDir: "applications/web",
132 });
133 ```
134
135 ## Add it to the Stack
136
137 Yield the site from your Stack and return its URL:
138
139 ```typescript
140 // alchemy.run.ts
141 import * as Alchemy from "alchemy";
142 import * as Effect from "effect/Effect";
143
144 export default Alchemy.Stack(
145 "MyFoldkitSite",
146 {
147 providers: Hetzner.providers(),
148 state: Alchemy.localState(),
149 },
150 Effect.gen(function* () {
151 const site = yield* Website;
152 return { url: site.url };
153 }),
154 );
155 ```
156
157 `site.url` is `http://{ipv4}:3000`. The site also exposes `server`
158 and `service` — they are `undefined` under `alchemy dev`.
159
160 ## Add environment variables
161
162 Set process environment variables through the top-level `env` map. Server
163 code reads private values from `process.env`; Vite inlines `VITE_*` values
164 into the browser build. Values must be strings or `Redacted` strings.
165
166 ```diff lang="typescript"
167 // alchemy.run.ts
168 export const Website = Hetzner.Website.Foldkit("Website", {
169 + env: {
170 + API_BASE: "https://api.example.com",
171 + VITE_API_URL: "https://api.example.com",
172 + },
173 });
174 ```
175
176 The values are copied onto `process.env` before Vite dev and build, and
177 onto the systemd unit. Server code reads `process.env.API_BASE`. Client code reads
178 `import.meta.env.VITE_API_URL`. Keep secrets out of `VITE_*` keys and serialized
179 Foldkit Flags.
180
181 ## Read the environment in client code
182
183 Type a custom public key with Vite's standard environment declaration:
184
185 ```typescript
186 // src/vite-env.d.ts
187 /// <reference types="vite/client" />
188
189 interface ImportMetaEnv {
190 readonly VITE_API_URL: string;
191 }
192 ```
193
194 ```typescript
195 const apiUrl = import.meta.env.VITE_API_URL;
196 ```
197
198 ## Deep links
199
200 A browser-only Foldkit app that uses URL routing (`Runtime.makeApplication` with
201 `routing`, `onUrlRequest`, and `onUrlChange`) resolves routes on the
202 client, so a deep link like `/counter/42` arrives as a request for a
203 file that doesn't exist.
204
205 For browser-only builds, `Foldkit` defaults `assets.notFoundHandling` to
206 `"single-page-application"`, which returns `index.html` (200) for
207 unmatched paths so the Foldkit runtime can resolve the route. Use
208 `"404-page"` to serve a real 404 instead:
209
210 ```typescript
211 export const Website = Hetzner.Website.Foldkit("Website", {
212 assets: { notFoundHandling: "404-page" },
213 });
214 ```
215
216 ## Local dev
217
218 `alchemy dev` runs Vite's own dev server (Foldkit's live reload
219 and devtools) instead of deploying; `site.url` is the local address and
220 no Server or Service is created. Wrap the site in `Alchemy.remote()`
221 to deploy the live unit even during dev.
222
223 Pin the dev server's address when several apps run in one Stack:
224
225 ```typescript
226 export const Website = Hetzner.Website.Foldkit("Website", {
227 dev: { host: "127.0.0.1", port: 5180, strictPort: true },
228 });
229 ```
230
231 ## Custom domain
232
233 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
234 — v1 does not create one. Alchemy adds an A record pointing at the
235 Server's public IPv4. `url` becomes `http://{domain}:3000`. There is
236 no TLS on the Service.
237
238 ```typescript
239 const site = yield* Hetzner.Website.Foldkit("Web", {
240 domain: "app.example.com",
241 zone,
242 });
243 ```
244
245 ## Where next
246
247 - [`Foldkit` reference](/providers/hetzner/website/foldkit) — every
248 prop and attribute
249 - [Vite](/hetzner/frontend/vite) — the same static-file unit, with
250 `assets.notFoundHandling`
251 - [Websites](/hetzner/frontend/websites) — the rest of the Hetzner
252 frontend family
253 - [Servers](/hetzner/compute/servers),
254 [Services](/hetzner/compute/services),
255 [DNS](/hetzner/networking/dns)