| 1 | > The packaged example deploys to Neon and passes live desktop/mobile counter and guide-navigation checks. |
| 2 | |
| 3 | # Neon Website: Vocs |
| 4 | |
| 5 | Deploys a real Vocs application with `Neon.Website.Vocs`. |
| 6 | |
| 7 | A Vocs documentation site with a guide, generated `/llms.txt`, and an interactive React counter embedded in `/counter` MDX. |
| 8 | |
| 9 | The packaged framework integration builds and deploys this example using its persistent local stack state. Live checks pass for desktop/mobile counter hydration and guide navigation, JSON GET/HEAD, and generated `/llms.txt`. The filtered fresh Vocs artifact lifecycle test also passes, including normal teardown. This verifies Vocs, not the full 13-framework live matrix. |
| 10 | |
| 11 | An earlier `artifact-browser` probe reported a sensitive-file rejection, but its retained log did not identify the selected file and its build output is no longer available. That historical failure was not reproduced by the actual example deployment. Sensitive dependency selections still fail closed and now report sanitized workspace-relative filenames; no exclusion was bypassed. |
| 12 | |
| 13 | ## Infrastructure |
| 14 | |
| 15 | `alchemy.run.ts` uses `Neon.providers()` and `Alchemy.localState()`. |
| 16 | The helper uses the application root by default. Live deployments without explicit |
| 17 | scope own a Neon Project in Ohio (`aws-us-east-2`), including its normal default |
| 18 | database, and a Node 24 Function. The app does not query that database. |
| 19 | No Docker daemon, container registry, or other cloud provider is used. |
| 20 | Pass an existing `project` or `branch` to reuse it without transferring ownership. |
| 21 | |
| 22 | The workspace supplies `alchemy` and `@alchemy.run/frontend-frameworks` through |
| 23 | `workspace:*` dependencies. `@vercel/nft` is installed for Neon artifact tracing. |
| 24 | Install dependencies from the repository root before |
| 25 | running commands in this directory. Authenticate Neon using the Alchemy profile |
| 26 | you intend to deploy with. |
| 27 | |
| 28 | ## Deploy |
| 29 | |
| 30 | ```sh |
| 31 | bun run deploy --profile testing |
| 32 | ``` |
| 33 | |
| 34 | The stack returns `url`. Framework configuration, application sources, and public |
| 35 | assets are included in this example; the Website helper owns the deployment adapter. |
| 36 | |
| 37 | ## Develop |
| 38 | |
| 39 | ```sh |
| 40 | bun run dev |
| 41 | ``` |
| 42 | |
| 43 | This runs the native framework dev server without creating an implicit Website-owned |
| 44 | Neon backend. Explicit backend resources remain live resources. Apply |
| 45 | `Alchemy.remote()` to the Website Effect to deploy a real Function during dev. |
| 46 | Cloud-only `function` and `domain` outputs are absent locally. |
| 47 | |
| 48 | ## Verify |
| 49 | |
| 50 | ```sh |
| 51 | ALCHEMY_PROFILE=testing bun test test/integ.test.ts |
| 52 | ``` |
| 53 | |
| 54 | The integration suite destroys previous stack state, deploys the actual app, |
| 55 | requests its page, verifies the static JSON asset, and destroys the stack. |
| 56 | Set `NO_DESTROY=1` only when intentionally keeping the deployment for inspection. |
| 57 | |
| 58 | For browser validation, open the returned URL. Open `/counter` and click **count: 0**; it becomes **count: 1**. |
| 59 | Every app also serves `/example.json` with a framework label and greeting. |
| 60 | |
| 61 | ## Destroy |
| 62 | |
| 63 | ```sh |
| 64 | bun run destroy --profile testing |
| 65 | ``` |
| 66 | |
| 67 | ## Packaging and security |
| 68 | |
| 69 | The Function receives a deterministic ZIP with a root Fetch `index.mjs`; it is not a |
| 70 | listening server or S3 website. Runtime dependencies are traced with `@vercel/nft`. |
| 71 | Only traced pnpm dependency files are materialized, with Node 24 resolution hooks |
| 72 | preserving canonical package identity. Vocs configuration is bundled so production |
| 73 | need not load its Vite configuration tooling. Validated Linux ARM64 ELF addons and |
| 74 | shared libraries are accepted; incompatible native binaries remain rejected. |
| 75 | `.env` files, credential files, and source maps remain excluded. |
| 76 | |
| 77 | Framework public environment prefixes are intentionally browser-visible. Keep secrets |
| 78 | out of those variables; `Redacted` protects infrastructure output, not arbitrary |
| 79 | framework build-time substitution. Never put `NEON_API_KEY` in Website `env`. |
| 80 | |
| 81 | Optional `domain` registers a custom hostname and returns `domain.cnameTarget`. |
| 82 | Publish a DNS-only CNAME and verify HTTPS independently; registration is not proof |
| 83 | of certificate readiness. Functions have public URLs, so authenticate private |
| 84 | application routes in the handler. |