Environment Rules

Rule

Scope: All apps and packages.

Goals

  • Single source of truth for environment schemas.
  • No ad-hoc process.env reads in app/package code.
  • Clear separation between server-only vars and client-safe vars.

Packages vs Apps

  • MUSTIn packages and server libraries, import from a shared env package (e.g., @project/env/server).
  • SHOULDIn Next.js apps, import from the env package's next export (e.g., @project/env/next).
  • SHOULDApps create their own env.ts files for app-specific variables.
  • NEVERRead process.env.X directly in feature code. Only the env schema files should touch process.env.

Schemas and Sources

  • Shared package: packages/env
    • /server — server-only variables (Node/server contexts)
    • /next — Next.js app variables (server + client)
  • App-local schema: apps/<app>/env.ts for app-specific variables (optional).

Client vs Server

  • MUSTClient-available vars MUST be prefixed NEXT_PUBLIC_.
  • SHOULDNarrow exposure: only export what the client needs.

Adding Variables

  1. Decide the scope and add the key to the correct schema.
  2. Update runtimeEnv mapping for every added key.
  3. Use the typed import in code (no direct process.env).

Safety

  • NEVERLog secrets. See security.md.
  • NEVERCommit .env files.
  • SHOULDFail fast on validation errors (default behavior).