Skip to content

CMS environment validation centralization

Problem

CMS environment validation is deliberately scattered across feature-owning modules and shared server packages (assets, import, AI, seed, proxy, pagination, shared rate-limit driver). While this keeps concerns isolated and supports lazy parsing, it makes the full env contract undiscoverable — developers must grep to find all supported env vars.

The central apps/cms/src/lib/validations/env.ts explicitly lists the scattered locations in comments (lines 7–14), including shared-parser-owned vars (RATE_LIMIT_DRIVER, UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN via @open-learning-hub/server/rate-limit), confirming this is a known trade-off.

Proposal

Add apps/cms/src/lib/env-registry.ts that:

  1. Imports all feature-scoped schemas and shared parser schemas used by CMS runtime
  2. Exports a merged schema (intersection) for documentation/validation tooling
  3. Optionally generates a ENV_VARS.md from the registry

Keep runtime parsing in feature modules — this is a discoverability fix only, not a runtime change.

Acceptance criteria

  • env-registry.ts re-exports all feature schemas
  • Running the registry at startup in development validates all vars eagerly
  • Existing lazy-loading behavior in production unchanged
  • npm run check passes

Out of scope

  • Changing where env vars are parsed at runtime
  • Migrating to t3-env or similar libraries

Notes / decisions log

  • 2026-07-07: Proposed. Low priority — current comment-based documentation in env.ts is functional but not machine-readable.
  • 2026-07-07: Expanded scope to include shared package-owned CMS env vars (RATE_LIMIT_DRIVER, UPSTASH_*) introduced with shared @open-learning-hub/server/rate-limit.
  • 2026-07-09: Deferred — moved to tickets/deferred/; no active implementation planned.