Your app needs passwords and keys to reach its database, its payment provider, its AI services. Put even one of those in your code and it goes wherever the code goes: shared with someone, pushed to a copy online, pasted to your agent. Any of those hands strangers the keys. This chapter keeps every secret out of your codebase from the start.
1.11.1What counts as a secret
A secret is any value that lets someone act as you or your app: a database password, an API key (the password a service hands you so its systems know the request is yours), a payment token, an auth signing key. The test is simple: if leaking it costs you money or access, it is a secret.
Everything else is just config, plain settings like a page title or a feature switch. Config is safe to share; secrets never are. This chapter is about the secrets.
1.11.2Keys never touch the code
The rule a professional never breaks: a secret is never written in the code itself. Code gets shared, pushed to your repo, copied between machines, pasted to your agent, and a key sitting inside it travels to every one of those places.
Instead, secrets live outside the code, in environment variables: values the app reads from its surroundings at startup, by name. The code says "give me the database password," never the password itself.
1.11.3One .env file, never committed
The standard home for those values is a file named .env in your project, one KEY=value per line, that your code reads when it starts. This file never leaves your machine: you add it to your .gitignore so version control skips it and it is never committed.
Beside it you commit a .env.example: the same key names with blank or fake values. Anyone else, including your future self, can then see which keys exist without seeing their values. The real secrets stay local, the list of what is needed is shared.
1.11.4Rotate anything that leaks
If a secret ever slips out, in a screenshot, a commit, a pasted log, treat it as burned. Rotate it: generate a fresh key at the provider and replace the old one, which instantly makes the leaked copy useless. Do it the moment you notice, not later.
Watch out: a secret pushed to your repo does not disappear when you delete the line, it stays in the history. Rotating the key is the only real fix.
1.11.5Production keeps its keys somewhere else
Your .env never leaves your machine, which is the whole point of it. It is also why nothing you set up today reaches the server your app will eventually run on.
You do not need to solve that yet. When you deploy, the same key names get set as environment variables in your host's own dashboard or command line. Your code reads them exactly as it does now.
A dedicated secret manager is a service whose only job is holding keys and handing them out. It earns its place later, once several people or machines need the same ones.
1.11.6Wire it up for your stack
This prompt has your agent set secret handling up correctly for whatever stack you chose:
Do this now: create the git-ignored .env and the .env.example beside it today, before your first key exists, so there is never a moment where a secret has nowhere to go but your code.
