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

main
mdx 255 lines 7.62 KB
Raw
1 ---
2 title: Foldkit
3 description: Deploy Foldkit SPA, SSR, SSG, and hybrid applications to Railway 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 `Railway.Website.Foldkit` deploys a [Foldkit](https://foldkit.dev) app to
13 Railway. 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 Railway from "@alchemy.run/railway";
123
124 export const Website = Railway.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 = Railway.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: Railway.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 the generated `https://{name}.up.railway.app`. The
158 site also exposes `service` and `project` — they are `undefined`
159 under `alchemy dev`.
160
161 ## Add environment variables
162
163 Set process environment variables through the top-level `env` map. Server
164 code reads private values from `process.env`; Vite inlines `VITE_*` values
165 into the browser build. Values must be strings or `Redacted` strings.
166
167 ```diff lang="typescript"
168 // alchemy.run.ts
169 export const Website = Railway.Website.Foldkit("Website", {
170 + env: {
171 + API_BASE: "https://api.example.com",
172 + VITE_API_URL: "https://api.example.com",
173 + },
174 });
175 ```
176
177 The values are copied onto `process.env` before Vite dev and build, and
178 onto the Service. Server code reads `process.env.API_BASE`. Client code reads
179 `import.meta.env.VITE_API_URL`. Keep secrets out of `VITE_*` keys and serialized
180 Foldkit Flags.
181
182 ## Read the environment in client code
183
184 Type a custom public key with Vite's standard environment declaration:
185
186 ```typescript
187 // src/vite-env.d.ts
188 /// <reference types="vite/client" />
189
190 interface ImportMetaEnv {
191 readonly VITE_API_URL: string;
192 }
193 ```
194
195 ```typescript
196 const apiUrl = import.meta.env.VITE_API_URL;
197 ```
198
199 ## Deep links
200
201 A browser-only Foldkit app that uses URL routing (`Runtime.makeApplication` with
202 `routing`, `onUrlRequest`, and `onUrlChange`) resolves routes on the
203 client, so a deep link like `/counter/42` arrives as a request for a
204 file that doesn't exist.
205
206 For browser-only builds, `Foldkit` defaults `assets.notFoundHandling` to
207 `"single-page-application"`, which returns `index.html` (200) for
208 unmatched paths so the Foldkit runtime can resolve the route. Use
209 `"404-page"` to serve a real 404 instead:
210
211 ```typescript
212 export const Website = Railway.Website.Foldkit("Website", {
213 assets: { notFoundHandling: "404-page" },
214 });
215 ```
216
217 ## Local dev
218
219 `alchemy dev` runs Vite's own dev server (Foldkit's live reload
220 and devtools) instead of deploying; `site.url` is the local address and
221 no Project or Service is created. Wrap the
222 site in `Alchemy.remote()` to deploy the live Service even during
223 dev.
224
225 Pin the dev server's address when several apps run in one Stack:
226
227 ```typescript
228 export const Website = Railway.Website.Foldkit("Website", {
229 dev: { host: "127.0.0.1", port: 5180, strictPort: true },
230 });
231 ```
232
233 ## Custom domain
234
235 Pass a hostname to attach a
236 [`Railway.CustomDomain`](/railway/networking) (`targetPort` 3000).
237 `url` becomes `https://{domain}`.
238
239 ```typescript
240 const site = yield* Railway.Website.Foldkit("Web", {
241 domain: "app.example.com",
242 });
243 ```
244
245 ## Where next
246
247 - [`Foldkit` reference](/providers/railway/website/foldkit) — every
248 prop and attribute
249 - [Vite](/railway/frontend/vite) — the same static-file Service for
250 any Vite app
251 - [Websites](/railway/frontend/websites) — the rest of the Railway
252 frontend family
253 - [Projects](/railway/compute/projects),
254 [Services](/railway/compute/services),
255 [Custom domains](/railway/networking)