| Surface | Local source | Visibility |
|---|---|---|
| Node scripts and web development | apps/web/.env | Server variables stay server-only |
| Local workerd | apps/web/.dev.vars and Wrangler bindings | Worker configuration |
| Expo | apps/mobile/.env | EXPO_PUBLIC_ values are bundled into the app |
| Production/preview | Worker secrets, bindings and workflow inputs | Server secrets must not become build-time public values |
packages/env validates each boundary separately. Web public configuration includes VITE_SITE_URL; native uses EXPO_PUBLIC_SERVER_URL. Never put credentials under public prefixes. Do not paste complete environment files into logs, issues or documentation.
Database and storage
Node uses DATABASE_URL. Production workerd uses Hyperdrive; its connection string belongs to the current invocation. Keep Hyperdrive caching disabled. Local built-Worker tests can override the Hyperdrive connection string with an isolated password-bearing local URL.
R2 credentials, bucket configuration and files gateway settings must describe the same environment. Public file URLs are an application concern; private objects still require authorization through the gateway.
Optional providers
Payments require provider selection and provider credentials, plus their visibility flags. AI requires provider configuration and ai.assistant. Email chooses an available transport in a defined order. A flag alone cannot configure an external account.
Run pnpm setup to populate or repair configuration and pnpm doctor to diagnose it. Keep environment examples descriptive; real values belong in ignored local files or the intended secrets store.
Key files
packages/env/src/server.tspackages/env/src/web.tspackages/env/src/native.tsapps/web/wrangler.jsonc