env-var-canon

name

env-var-canon

description

The authoritative environment-variable registry for the Unite-Group Nexus. Use whenever adding, reading, renaming, or debugging an env var or secret — new integration config, a `process.env.X` read, an auth/OAuth wiring, a cron secret, a "which variable holds this" question, or a "works locally but not in prod" symptom. Also use before pinning any variable name in code, and when reconciling the two credential planes (Vercel prod vs the local hermes fleet). Prevents the `APIFY_API_KEY` vs `APIFY_API_TOKEN` class of drift.

Env-var canon

The Nexus reads 314 distinct environment variables across apps/ and packages/, and there is no central env module — every read is a raw process.env.X. That sprawl is how drift happens: a second name for the same secret (APIFY_API_KEY vs APIFY_API_TOKEN), a client read of a server-only secret, or a value set on one plane but not the other. This skill is the single place a name is canonical before it is pinned anywhere.

The canon rule

1. One canonical name per secret. Before introducing a variable, grep for an existing name — grep -rInE "process\.env\.[A-Z0-9_]*<STEM>" apps packages. If any spelling exists, reuse it. Never mint a synonym.
2. NEXT_PUBLIC_ means the browser can read it. Prefix only values that are safe to ship to the client (URLs, anon keys, public app URL). A server secret must never carry NEXT_PUBLIC_ — that leaks it into the bundle.
3. Route new reads through one accessor. Until a central env module exists, at minimum read each variable in one module and pass the value down — do not scatter process.env.X across route handlers. (Building the central typed accessor is the standing direction; see Roadmap below.)