clover's git

the-knife

1	---
2	title: Foldkit
3	description: Package a client-only Foldkit Vite app for Neon Functions with SPA routing.
4	sidebar:
5	order: 11
6	---
7
8	`Neon.Website.Foldkit` is the client-only Vite composition with SPA routing. It
9	packages built assets with a Node 24 Fetch file handler in a Neon Function ZIP,
10	not a Foldkit SSR server, container, listening Bun server, or S3 website.
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), then install in the app directory:
17
18	Install [Alchemy and its matching Effect dependencies](/getting-started) first;
19	use Node 24 for this build toolchain.
20
21	```sh
22	pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft
23	```
24
25	Keep the `foldkit()` plugin from `@foldkit/vite-plugin` in `vite.config.*` and
26	retain your application's normal entry configuration. The constructor delegates
27	to Vite; there is no separate server adapter to configure.
28
29	## Define the stack
30
31	```typescript
32	// alchemy.run.ts
33	import * as Alchemy from "alchemy";
34	import * as Neon from "alchemy/Neon";
35	import * as Effect from "effect/Effect";
36
37	export default Alchemy.Stack(
38	"NeonFoldkit",
39	{ providers: Neon.providers(), state: Alchemy.localState() },
40	Effect.gen(function* () {
41	const site = yield* Neon.Website.Foldkit("Web", {
42	rootDir: ".",
43	});
44	return { url: site.url };
45	}),
46	);
47	```
48
49	Unmatched GET/HEAD paths fall back to `index.html` for client-side routes.
50	For a multi-page build with a `404.html`, set `assets.notFoundHandling` to
51	`"404-page"`. Like Vite, `vite.outDir` and `vite.base` are supported overrides.
52
53	`env` values with Vite's `VITE_*` prefix are embedded into the browser build.
54	There is no application server here to consume private runtime values; use a
55	separate backend for privileged operations.
56
57	## Develop and deploy
58
59	```sh
60	pnpm exec alchemy dev
61	pnpm exec alchemy deploy
62	pnpm exec alchemy destroy
63	```
64
65	Run separately, destroying when finished. Dev uses Vite's native server and HMR,
66	returns a local URL, and creates no implicit Neon resources. Append
67	`.pipe(Alchemy.remote())` to the Website Effect to use live deployment during dev.
68
69	Live deploy creates an Ohio Project if no scope is supplied. Pass either
70	`project` or `branch` for an existing backend; choose Ohio for combined storage
71	use. Read [scope and credentials](/neon/frontend/vite#scope-and-credentials):
72	account keys and privileged branch tokens must not reach this browser bundle.
73
74	:::caution[Deployment limits]
75	Complete live framework acceptance remains unverified. Neon probes have served
76	old code/env after new deployment metadata became active. Static assets are
77	served inside the Function without an added CDN, and domain registration does
78	not validate TLS. See the
79	[shared deployment limits](/neon/frontend/vite#environment-and-deployment-limits).
80	:::
81
82	## Reference
83
84	- [Foldkit API](/providers/neon/website/foldkit)
85	- [Runnable Foldkit example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-foldkit)