| name | startup-validation-env-order |
| description | Keep apps/*/lib/startup/validation.ts push order aligned with apps/*/.env.example section order when practical. Use when adding env vars, startup validation entries, or editing validation.ts. |
| version | 1.0.0 |
Startup validation order vs env files
When to use
When adding or reordering entries in:
apps/api/src/lib/startup/validation.tsapps/management-api/src/lib/startup/validation.ts
especially after adding vars to the matching apps/<app>/.env.example.
Rule
Keep validation results.push(...) order aligned with the authoritative env template
(apps/<app>/.env.example) when practical:
- Section order — Group validation blocks in the same sequence as env file sections
(e.g. General → API Configuration → Auth → Database → …).
- Within a section — Push validations for vars in the same order they appear under that
section header in
.env.example.
- Last section = last block — Vars in the final env section belong at the end of
validateAllEnvironmentVariables, not mixed into an earlier category block.
- Comments — Optional short comment tying a validation block to the env section name
helps future edits stay aligned.
Exceptions (OK to diverge)
- Early validation — Vars that must be read before others (e.g.
ACCOUNT_SIGNUP_MODE
before conditional mailer checks) may be validated earlier than their env section.
- Grouped helpers — Custom validators may stay together even if env keys are scattered;
keep the block near the related env section when possible.
- Display order — Startup output is grouped by validation
category, not file order;
alignment is for maintainer ergonomics when editing both files side by side.
Files to keep in sync
When adding an env var:
apps/<app>/.env.example — authoritative section + key orderapps/<app>/src/lib/startup/validation.ts — matching push order (same app)infra/config/env-templates/*.env.example when the var is shared across apps
References
- startup-validation-env-order rule (
.cursor/rules/startup-validation-env-order.mdc)
- config-type-safety rule — no silent defaults in app
config/index.ts
- env-file-formatting — env value formatting
- api — API startup validation patterns
