4.2 Environment Variables and Secrets
An environment variable is not automatically a secret — and in frontend code, usually the opposite.
This page exists because the mistake it describes is common, easy to make, and occasionally catastrophic.
Environment variables are not secret by virtue of being environment variables. In a frontend build they are frequently the opposite: inlined into JavaScript that anyone can read with view-source.
The rule
Anything bundled into client JavaScript is public. Permanently, to everyone, including in old deploys that are still cached somewhere.
Frameworks mark the boundary with a prefix:
NEXT_PUBLIC_API_URL=https://api.example.com # sent to the browser
VITE_API_URL=https://api.example.com # sent to the browser
DATABASE_URL=postgres://... # server onlyThe prefix is not a security feature — it is a declaration. It says "I understand this will be visible to users." Variables without it are simply never inlined.
Two groups
Diagram source
flowchart TD
A[Environment Variables]
B[Browser Safe]
C[Server Only]
A --> B
A --> C
B --> D[Public API URL]
B --> E[Analytics ID]
C --> F[Database Password]
C --> G[Private API Key]
C --> H[JWT Signing Secret]Sort every variable into one of these before adding it. The question is not "is this sensitive?" but "am I willing to print this on the homepage?"
Never write something like:
NEXT_PUBLIC_DATABASE_PASSWORD=...unless your career goal is to author an incident report. The prefix does not protect it; the prefix is what exposes it.
Publishable vs secret keys
Many third-party services issue two keys, and the naming is a useful signal:
pk_live_... publishable — designed for client-side use
sk_live_... secret — server only, full account accessStripe's publishable key is meant to be in your bundle; it can only create payment intents. The secret key can issue refunds. Services that offer this split have already done the thinking for you — use the right one rather than the one that made the code shorter.
Supabase's anon key is the same idea, with an important caveat: it is safe
only if row-level security is configured. The key assumes a policy layer
exists behind it.
Build time vs runtime
The distinction that causes the most confusion in containerized frontends.
Client-side variables are inlined during npm run build. They are baked into
the output. Changing the environment at runtime does nothing, because there is
no variable left to change — just a string literal in a bundle.
Server-side vars read at runtime → one image, many environments
Client-side vars fixed at build time → one image per environmentThis breaks "build once, deploy everywhere" for anything client-side. Options:
- Build per environment. Simple, but staging and production run different artifacts, so you never tested exactly what you shipped.
- Fetch public config at runtime. A
/configendpoint or a small inline script in the document. One artifact everywhere, at the cost of one request or a slightly less cacheable document.
The second is better at scale. The first is fine for most teams.
Where secrets should live
.env.local local development only; gitignored
GitHub Secrets CI/CD
Secrets Manager production (AWS/GCP secret stores, Vault)
Platform env vars Vercel/Netlify project settingsCommit a .env.example with every key and no values, so a new developer knows
what to set without anyone pasting real credentials into chat.
If a secret is committed, rotating it is the fix — not deleting the commit. It is in the reflog, in every clone, in forks, and quite possibly already scraped. Treat any secret that ever touched a repository as compromised.
Checking what you shipped
A worthwhile habit after any change to environment handling. Search the built output for something that should not be there:
npm run build
grep -r "sk_live" .next/ dist/ 2>/dev/null && echo "LEAK" || echo "clean"Worth adding to CI as a guard against the specific mistake of someone adding a
NEXT_PUBLIC_ prefix to make an error go away.