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

main
mdx 92 lines 3.69 KB
Raw
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.run/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)