@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, 06:00 UTC

main
mdx 152 lines 5.64 KB
Raw
1 ---
2 title: Foldkit
3 description: Deploy Foldkit SPA, SSR, SSG, and hybrid applications to Neon Functions with native local development.
4 sidebar:
5 order: 11
6 ---
7
8 `Neon.Website.Foldkit` supports browser-only SPAs, server-side rendering (SSR),
9 static site generation (SSG), and hybrid rendering. It packages Foldkit's assets and
10 optional generated handler as a Node 24 Fetch module in a Neon Function ZIP.
11
12 ## Prepare the app
13
14 Use an existing Foldkit app or the
15 [runnable Foldkit example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-foldkit).
16 Configure [deployment credentials](/neon/setup) and install
17 [Alchemy and its matching Effect dependencies](/getting-started). Use Node 24
18 for this build toolchain, then install the build integration in the app directory:
19
20 ```sh
21 pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft
22 ```
23
24 Keep the `foldkit()` plugin from `@foldkit/vite-plugin` in `vite.config.*` and
25 retain your application's normal entry configuration. No application adapter or
26 server wrapper is required.
27
28 ## Server rendering and prerendering
29
30 Configure rendering in the application's `foldkit(...)` plugin. This example
31 uses Foldkit 0.167.0, `@foldkit/vite-plugin` 0.27.0 and compatible Effect
32 dependencies:
33
34 ```typescript
35 // vite.config.ts
36 import { foldkit } from "@foldkit/vite-plugin";
37 import { defineConfig } from "vite";
38
39 export default defineConfig({
40 plugins: [
41 foldkit({
42 ssr: {
43 serverEntry: "/src/entry.server.ts",
44 clientEntry: "/src/entry.ts",
45 build: true,
46 },
47 }),
48 ],
49 });
50 ```
51
52 The server entry exports `renderPage` and `renderDocument`. Import stylesheets
53 from the client entry and use `Runtime.hydrate` to start the browser application.
54 Remove the source `index.html` for this build: Foldkit generates the complete
55 HTML document, including the client script, stylesheets and module preload links.
56
57 ```typescript
58 // src/entry.server.ts
59 import { Server } from "foldkit/experimental";
60
61 export const renderDocument = Server.renderDocument;
62 ```
63
64 Keep your application's `renderPage` export alongside the document renderer.
65 Foldkit currently exposes its server rendering API through `foldkit/experimental`;
66 see its [server rendering guide](https://foldkit.dev/core/server-rendering) for
67 the application and hydration contract.
68
69 For static site generation (SSG), change `build` to `{ prerender: true }` and
70 export the URLs to generate from the server entry:
71
72 ```typescript
73 // src/entry.server.ts
74 export const prerenderPaths = ["/", "/about"];
75 ```
76
77 SSG renders those URLs during the build. SSR renders a page when its request
78 arrives. A hybrid application prerenders some URLs and renders others on request.
79 The same `renderPage` and `renderDocument` exports serve both delivery policies.
80
81 The same Website declaration deploys the client assets and generated handler.
82 GET and HEAD requests serve matching assets and prerendered pages first;
83 remaining requests go to the handler. Other methods bypass static assets.
84 The application owns its response status and headers through `renderPage`.
85 For an SSG-only application, return 404 for URLs outside its generated route set;
86 allowing those URLs to render on request makes the deployment hybrid.
87
88 Browser-only builds use SPA fallback. Server builds send unmatched requests to
89 the handler. Explicit `assets.notFoundHandling` settings override these defaults.
90
91 Vite's resolved `base` also mounts the client assets. With `base: "/app/"`,
92 `/app/assets/main.js` serves `assets/main.js` from the client output. SPA fallback
93 is limited to that prefix; server handlers receive the original URL.
94
95 ## Define the stack
96
97 ```typescript
98 // alchemy.run.ts
99 import * as Alchemy from "alchemy";
100 import * as Neon from "@alchemy.run/neon";
101 import * as Effect from "effect/Effect";
102
103 export default Alchemy.Stack(
104 "NeonFoldkit",
105 { providers: Neon.providers(), state: Alchemy.localState() },
106 Effect.gen(function* () {
107 const site = yield* Neon.Website.Foldkit("Web", {
108 rootDir: ".",
109 });
110 return { url: site.url };
111 }),
112 );
113 ```
114
115 Browser-only builds serve `index.html` for unmatched GET/HEAD paths so the
116 client router can resolve deep links.
117 For a multi-page build with a `404.html`, set `assets.notFoundHandling` to
118 `"404-page"`. `vite.outDir` overrides the build output directory.
119
120 `env` values with Vite's `VITE_*` prefix are embedded into the browser build.
121 Server-rendered apps read private runtime values from `process.env`. Keep secrets
122 out of `VITE_*` keys and serialized Foldkit Flags because both reach the browser.
123
124 ## Develop and deploy
125
126 ```sh
127 pnpm exec alchemy dev
128 pnpm exec alchemy deploy
129 pnpm exec alchemy destroy
130 ```
131
132 Run separately, destroying when finished. Dev uses Vite's native server with Foldkit live reload,
133 returns a local URL, and creates no implicit Neon resources. Append
134 `.pipe(Alchemy.remote())` to the Website Effect to use live deployment during dev.
135
136 Live deploy creates an Ohio Project if no scope is supplied. Pass either
137 `project` or `branch` for an existing backend; choose Ohio for combined storage
138 use. Read [scope and credentials](/neon/frontend/vite#scope-and-credentials):
139 account keys and privileged branch tokens must not reach this browser bundle.
140
141 :::caution[Deployment limits]
142 Complete live framework acceptance remains unverified. Neon probes have served
143 old code/env after new deployment metadata became active. Static assets are
144 served inside the Function without an added CDN, and domain registration does
145 not validate TLS. See the
146 [shared deployment limits](/neon/frontend/vite#environment-and-deployment-limits).
147 :::
148
149 ## Reference
150
151 - [Foldkit API](/providers/neon/website/foldkit)
152 - [Runnable Foldkit example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-foldkit)