| 1 | > Runtime acceptance is pending the Neon deployment and browser checks; this example is not yet verified on Neon. |
| 2 | |
| 3 | # Neon Website: Next.js |
| 4 | |
| 5 | Deploys a real Next.js application with `Neon.Website.Nextjs`. |
| 6 | |
| 7 | An App Router page reads `GREETING` on each request. A client component increments a counter and calls `/api/hello` without a database. A server-action form redirects to a result that survives refresh. `/api/stream` emits two SSE messages, `/redirect` returns a temporary redirect, and an unoptimized Next Image renders `/logo.svg`. |
| 8 | |
| 9 | The production artifact passes isolated Linux ARM64/glibc Node 24 checks, including Sharp WebP optimization, assets, HEAD, and streaming. Desktop/mobile browser checks against the source-generated artifact pass counters, greeting fetches, server actions, refresh persistence, and the redirect link. Redirects preserve the request protocol, hostname, and port; Next itself normalizes loopback IP hostnames to `localhost`. Fresh Neon deployment reaches the API but fails with `FunctionDeploymentFailed`, so live browser acceptance and updates remain unverified. The full 13-framework live matrix is not green. |
| 10 | |
| 11 | ## Infrastructure |
| 12 | |
| 13 | `alchemy.run.ts` uses `Neon.providers()` and `Alchemy.localState()`. |
| 14 | The helper uses the application root by default. Live deployments without explicit |
| 15 | scope own a Neon Project in Ohio (`aws-us-east-2`), including its normal default |
| 16 | database, and a Node 24 Function. The app does not query that database. |
| 17 | No Docker daemon, container registry, or other cloud provider is used. |
| 18 | Pass an existing `project` or `branch` to reuse it without transferring ownership. |
| 19 | |
| 20 | The workspace supplies `alchemy` and `@alchemy.run/frontend-frameworks` through |
| 21 | `workspace:*` dependencies. `@vercel/nft` is installed for Neon artifact tracing. |
| 22 | Install dependencies from the repository root before |
| 23 | running commands in this directory. Authenticate Neon using the Alchemy profile |
| 24 | you intend to deploy with. |
| 25 | |
| 26 | ## Deploy |
| 27 | |
| 28 | ```sh |
| 29 | bun run deploy --profile testing |
| 30 | ``` |
| 31 | |
| 32 | The stack returns `url`. Framework configuration, application sources, and public |
| 33 | assets are included in this example; the Website helper owns the deployment adapter. |
| 34 | |
| 35 | ## Develop |
| 36 | |
| 37 | ```sh |
| 38 | bun run dev |
| 39 | ``` |
| 40 | |
| 41 | This runs the native framework dev server without creating an implicit Website-owned |
| 42 | Neon backend. Explicit backend resources remain live resources. Apply |
| 43 | `Alchemy.remote()` to the Website Effect to deploy a real Function during dev. |
| 44 | Cloud-only `function` and `domain` outputs are absent locally. |
| 45 | |
| 46 | ## Verify |
| 47 | |
| 48 | ```sh |
| 49 | ALCHEMY_PROFILE=testing bun test test/integ.test.ts |
| 50 | ``` |
| 51 | |
| 52 | The integration suite destroys previous stack state, deploys the actual app, |
| 53 | requests its page, dynamic endpoint, verifies the static JSON asset, and destroys the stack. |
| 54 | Set `NO_DESTROY=1` only when intentionally keeping the deployment for inspection. |
| 55 | |
| 56 | For browser validation, open the returned URL. Click **count: 0**; it becomes **count: 1**. Click **Load greeting** and check that the greeting appears below the button. |
| 57 | Every app also serves `/example.json` with a framework label and greeting. |
| 58 | |
| 59 | ## Destroy |
| 60 | |
| 61 | ```sh |
| 62 | bun run destroy --profile testing |
| 63 | ``` |
| 64 | |
| 65 | ## Packaging and security |
| 66 | |
| 67 | The Function receives a deterministic ZIP with a root Fetch `index.mjs`; it is not a |
| 68 | listening server or S3 website. Runtime dependencies are traced with `@vercel/nft`. |
| 69 | Only traced pnpm dependency files are materialized, with Node 24 resolution hooks |
| 70 | preserving canonical package identity. Exact-version Sharp Linux ARM64/glibc packages |
| 71 | are fetched with registry integrity checks; incompatible native binaries remain rejected. |
| 72 | Validated ELF addons and shared libraries are accepted. `.env` files, credential files, |
| 73 | and source maps remain excluded. |
| 74 | |
| 75 | Framework public environment prefixes are intentionally browser-visible. Keep secrets |
| 76 | out of those variables; `Redacted` protects infrastructure output, not arbitrary |
| 77 | framework build-time substitution. Never put `NEON_API_KEY` in Website `env`. |
| 78 | |
| 79 | Optional `domain` registers a custom hostname and returns `domain.cnameTarget`. |
| 80 | Publish a DNS-only CNAME and verify HTTPS independently; registration is not proof |
| 81 | of certificate readiness. Functions have public URLs, so authenticate private |
| 82 | application routes in the handler. |