add-env-variable

To safely add environment variables in TypeScript, use a schema-driven approach that updates the env mapping, documents the variable in .env.example, and adds unit tests to verify validation and defaults. This ensures configuration consistency and prevents runtime errors from misconfigurations.

Validating environment variables with zod enforces explicit validation rules at the application boundary, ensuring invalid or missing configuration fails fast during startup rather than causing unpredictable runtime errors in production.

The best way to keep .env.example and tests in sync is an end-to-end integration process that updates the schema, dotenv mapping, documentation, and unit tests simultaneously whenever a new environment variable is introduced to the codebase.

Updating env schema and tests involves modifying the zod schema in src/env.ts, updating the dotenv mapping, adding documentation to .env.example, and writing unit tests to verify that the validation rules and default values behave correctly.

Adding environment variables typically requires manual updates across src/env.ts, .env.example, and test files. Automating this process ensures schema validation, dotenv mapping, documentation, and test coverage are applied consistently without missing any required file modifications.

Adding an environment variable without updating validation tests risks undetected misconfigurations, where missing or invalid values bypass schema rules and cause runtime errors. Enforcing test coverage verifies defaults and validation logic to prevent these failures.