Environment Setup

Environment Setup

Setting up environment variables correctly ensures the project works the same across local, CI, and production. The checklist in tasks/epics/02-environment-management.mdx highlights three key capabilities:

  • .env.example covering all runtime variables
  • env.ts runtime validator using Zod
  • secrets loading strategy for CI and preview environments

Local Development

  1. Copy the example file and create your personal environment file:
cp .env.example .env.local
  1. Review .env.local and adjust the values for your machine.
  2. Run the dev servers:
pnpm dev

Runtime Validation

The packages/config package will expose an env.ts helper that parses and validates these variables at runtime. If any required variable is missing or malformed, the build fails with a descriptive message. This keeps misconfiguration from silently breaking deployments.

CI Secrets

In GitHub Actions (and similar CI systems), secrets are injected at runtime. They are never committed to the repository. The CI pipeline loads them from the secrets store and passes them into the build commands so no plaintext secrets appear in logs.

For background and the goals of this setup, see tasks/epics/02-environment-management.mdx in the repository.