Deployment

Deploy a Beignet app by validating configuration, checking route wiring, building the app, and confirming provider behavior in the target environment.

Preflight checks

Run these in CI before shipping:

bun run lint
bun test
bun run typecheck
bunx -p @beignet/cli beignet lint
bunx -p @beignet/cli beignet doctor --strict

bun test works even before the app has a package-level test script. The resource generator adds a test script when it creates starter tests, so bun run test is also fine after that point. beignet lint enforces Beignet dependency direction so core feature code does not reach into runtime, UI, or infra layers. doctor --strict is meant for CI: it reports app wiring drift that can be easy to miss during manual edits.

Environment configuration

Keep deploy-time configuration in lib/env.ts and validate it at startup. Avoid reading ad hoc environment variables inside route handlers, use cases, or infra adapters.

lib/env.ts       validates process.env
infra/app-ports.ts   receives typed env values
server/index.ts  installs providers and hooks

When a hosting platform only bundles explicitly referenced variables, use the strict runtime env helpers from Config so missing keys fail early.

Routes and OpenAPI

Before deployment, confirm the CLI can inspect the route map:

bunx -p @beignet/cli beignet routes

If your app exposes OpenAPI, make sure the OpenAPI route is generated from the same route list used by the server, typically with server.contracts or contractsFromRoutes(routes). Run doctor after changing contracts or route registration.

Providers

Production providers should be installed in server/providers.ts when your app has that file, or directly in the central server setup. Provider startup and teardown belong to the application lifecycle, not route handlers.

Check these before shipping:

• Database clients and migrations are ready for the target environment.
• Cache, mail, job, auth, logging, and rate-limit providers have required env.
• Unit of Work and after-commit event behavior are tested with the real adapter.
• Dev-only providers and devtools routes are gated appropriately.

Client base URLs

Server-side code should usually call internal functions directly. When it must use the HTTP client, createNextClient() resolves an absolute server URL from NEXT_PUBLIC_API_URL, serverBaseUrl, VERCEL_URL, or PORT. Browser clients can use same-origin relative requests behind the deployment platform's routing layer.

Keep client construction in client/ so base URL and auth behavior have one home.