clover's git

the-knife

1	---
2	title: Next.js
3	description: Build Next.js for a Neon Function Fetch entry and use next dev locally.
4	sidebar:
5	order: 3
6	---
7
8	`Neon.Website.Nextjs` runs `next build` and adapts Next's Node custom-server
9	handler to a Node 24 Fetch entry. The Function ZIP includes `.next`, public assets,
10	configuration, and traced runtime dependencies. This is not OpenNext, a container,
11	a listening Bun server, or an S3/CloudFront deployment.
12
13	## Prepare the app
14
15	Use an existing Next.js app or the
16	[runnable Next.js example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-nextjs).
17	Configure [deployment credentials](/neon/setup), then install in the app directory:
18
19	Install [Alchemy and its matching Effect dependencies](/getting-started) first;
20	use Node 24 for this build toolchain.
21
22	```sh
23	pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft
24	```
25
26	Keep `next.config.*`; no OpenNext config or adapter is required. The integration
27	uses installed package versions. Native runtime dependencies must be compatible
28	with the deployed Linux runtime, not merely your development machine.
29
30	## Define the stack
31
32	```typescript
33	// alchemy.run.ts
34	import * as Alchemy from "alchemy";
35	import * as Neon from "alchemy/Neon";
36	import * as Effect from "effect/Effect";
37
38	export default Alchemy.Stack(
39	"NeonNextjs",
40	{ providers: Neon.providers(), state: Alchemy.localState() },
41	Effect.gen(function* () {
42	const site = yield* Neon.Website.Nextjs("Web", {
43	rootDir: ".",
44	});
45	return { url: site.url };
46	}),
47	);
48	```
49
50	Next handles application routes and server rendering; the Fetch wrapper serves
51	static files from the packaged output. Server-side `env` values are process
52	environment; `NEXT_PUBLIC_*` values are build-time public configuration, not secrets.
53
54	## Develop and attempt deployment
55
56	```sh
57	pnpm exec alchemy dev
58	pnpm exec alchemy deploy
59	pnpm exec alchemy destroy
60	```
61
62	Run each separately, with `destroy` for cleanup. Native dev runs `next dev` and
63	returns its local URL without creating an implicit Project or Function. Append
64	`.pipe(Alchemy.remote())` to the Website Effect to use live deployment during dev;
65	this does not bypass artifact or runtime limitations.
66
67	The omitted scope creates an Ohio Project only on live deploy. Supply either
68	`project` or `branch` to select an existing backend; choose Ohio for combined
69	storage use. See [scope and credentials](/neon/frontend/vite#scope-and-credentials).
70
71	:::caution[Production verification remains open]
72	The final artifact passes isolated Linux ARM64/glibc Node 24 checks for assets,
73	HEAD, streaming, and Sharp WebP optimization. Desktop/mobile production-artifact
74	browser checks pass counters, greeting fetches, server actions, refresh persistence,
75	and redirect-link navigation. The source-generated Fetch bridge preserves the request
76	protocol, hostname, and port without rewriting redirect responses. Next itself
77	normalizes loopback IP hostnames to `localhost`. Initial live Neon deployment and
78	desktop/mobile interactions now pass after removing an unnecessary duplicate native
79	library from the artifact. Updates can still serve the previous artifact after Neon
80	accepts a new deployment, so complete lifecycle acceptance remains open.
81	:::
82
83	There is no provisioned ISR/revalidation cache, image-optimization service, or CDN.
84	Do not assume Next's local cache persists across Function instances. Live Function
85	updates have also served old code/env despite new deployment metadata. Custom
86	domains require separate DNS/HTTPS verification. Read the
87	[shared deployment limits](/neon/frontend/vite#environment-and-deployment-limits).
88
89	## Reference
90
91	- [Nextjs API](/providers/neon/website/nextjs)
92	- [Runnable Next.js example](https://github.com/alchemy-run/alchemy/tree/main/examples/neon-website-nextjs)