---
name: set-up-env-variables-and-secrets
description: Sets up environment variables and secrets safely - a .env.local that git ignores, a committed .env.example, values added on the host per environment, browser-safe prefixes only for public values, and a plan to rotate a key that leaked. Use when the user asks where to put API keys, how .env files work, or committed a secret key to git by mistake.
license: CC-BY-4.0
metadata:
  category: deployment
  tags: "secrets,security,hosting"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "env vars, .env, api keys, committed secret key, leaked key"
---

# Set up env variables and secrets

Keys and passwords live outside your code. Your code reads them from the environment, and each place it runs gets its own values.

## When to use
- You have an API key and do not know where to put it.
- A deploy works locally but not on the host because values are missing.
- You think you committed a key, or a scanner warned you.

## Steps
1. Create `.env.local` (or `.env`) for local values and add `.env*` to `.gitignore`, keeping `!.env.example`.
2. Commit `.env.example` with every variable name and a fake value, so others know what to set.
3. Read values in code with `process.env.NAME` (or your language's equivalent) and fail early with a clear message if one is missing.
4. Keep secrets server-side. Only values meant for the browser get a public prefix such as `NEXT_PUBLIC_` or `VITE_`.
5. Add the values on your host (Vercel, Netlify, Cloudflare, Railway) for each environment: development, preview and production.
6. Use separate keys for test and live, such as Stripe test keys in preview.
7. Redeploy after changing values. Most hosts only read them at build or start.
8. If a secret leaked, rotate it at the provider first, then remove it from the code. Deleting the commit is not enough.
9. Add a secret scanner (gitleaks or GitHub secret scanning) so it does not happen again.

```bash
# .env.example
DATABASE_URL=postgres://user:password@localhost:5432/app
STRIPE_SECRET_KEY=sk_test_replace_me
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

## Gotchas
- Anything with a public prefix is visible to every visitor. Never put secret keys there.
- Never paste real keys into chats, issues, screenshots or AI prompts.
- A key in git history stays readable even after you delete the file. Rotate it.
- Values with spaces or `#` may need quotes in `.env` files.

## Portability
Works with any framework and host. If you use a secrets manager (Doppler, 1Password, AWS Secrets Manager) instead of `.env` files, the same split of local, preview and production applies.

## Example prompt
"Where should I put my OpenAI and Stripe keys in my Next.js app, and how do I add them on Vercel without leaking them?"

## Done when
- No real secret is tracked by git, and `.env.example` lists every variable.
- Each host environment has its own values and the app starts without missing-variable errors.
- Any leaked key has been rotated.

---
House original by TheSkillVault (CC-BY-4.0).