clover's git

the-knife

1	---
2	title: Waku
3	description: Package Waku RSC and static pages for Neon Functions, with native Waku development.
4	sidebar:
5	order: 9
6	---
7
8	`Neon.Website.Waku` builds Waku's React Server Components handler and static pages
9	into a Node 24 Fetch artifact for a Neon Function. It reuses the Node build target,
10	but the deployed entry does not open a listening socket. No container or S3
11	website is created.
12
13	## Prepare the app
14
15	Use an existing Waku app or the
16	[runnable Waku example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-waku).
17	Keep the React/RSC peer versions compatible with your Waku version. Configure
18	[deployment credentials](/neon/setup), then install in the app directory:
19
20	Install [Alchemy and its matching Effect dependencies](/getting-started) first;
21	use Node 24 for this build toolchain.
22
23	```sh
24	pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft
25	```
26
27	Keep `waku.config.*`, but do not set `unstable_adapter`: the integration selects
28	Waku's Node adapter. The `waku` resource prop accepts `srcDir`, `distDir`, and
29	`basePath` overrides.
30
31	## Define the stack
32
33	```typescript
34	// alchemy.run.ts
35	import * as Alchemy from "alchemy";
36	import * as Neon from "alchemy/Neon";
37	import * as Effect from "effect/Effect";
38
39	export default Alchemy.Stack(
40	"NeonWaku",
41	{ providers: Neon.providers(), state: Alchemy.localState() },
42	Effect.gen(function* () {
43	const site = yield* Neon.Website.Waku("Web", {
44	rootDir: ".",
45	});
46	return { url: site.url };
47	}),
48	);
49	```
50
51	The Fetch wrapper serves built files and resolves extensionless HTML paths before
52	falling through to Waku's handler. Dynamic rendering and RSC requests use that
53	handler. Server code can read private `env` values from `process.env`; never pass
54	service credentials through client-component props or public build variables.
55
56	## Develop and deploy
57
58	```sh
59	pnpm exec alchemy dev
60	pnpm exec alchemy deploy
61	pnpm exec alchemy destroy
62	```
63
64	Run separately, destroying when finished. Dev runs Waku's native development
65	server and HMR, returns a local URL, and creates no implicit Project or Function.
66	Append `.pipe(Alchemy.remote())` to the Website Effect to use live deployment during dev.
67
68	Without scope, live deploy creates an Ohio Project. Pass either `project` or
69	`branch` for an existing backend; choose Ohio when adding storage. See
70	[scope and credentials](/neon/frontend/vite#scope-and-credentials).
71
72	:::caution[Deployment limits]
73	Complete live framework acceptance remains unverified. Native RSC development
74	does not establish production acceptance, and Neon probes have served old
75	code/env after deployment metadata changed. No CDN or durable framework cache
76	is added; domain registration is not TLS validation. See the
77	[shared deployment limits](/neon/frontend/vite#environment-and-deployment-limits).
78	:::
79
80	## Reference
81
82	- [Waku API](/providers/neon/website/waku)
83	- [Runnable Waku example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-waku)