ADR-0015 · Um único .env.example, distribuído por projeto

Status: aceito (23/10/2026) — entregue na versão 2.2.0.

Contexto

Cada app e pacote tinha o próprio .env.example, e a raiz tinha outro para o docker-compose.yml. Os arquivos repetiam variáveis com valores diferentes, traziam dezenas de chaves que o código não lê mais e, no caso da raiz, credenciais reais de produção versionadas (R-14). Não havia um lugar para ver quais variáveis cada projeto precisa.

Decisão

1. Um só .env.example, na raiz, com todos os exemplos do monorepo, divididos em seções: compartilhadas (banco, e-mail, token de pagamento, Redis), web, order-lifecycle, docs e docker-compose. Cada seção explica quem lê cada variável.
2. Destino explícito por seção com o marcador #@target <pasta>, …. Variáveis com o mesmo valor em vários projetos ficam numa seção compartilhada com vários destinos (ex.: PAYMENT_BYPASS_TOKEN para web e API).
3. Cada app continua lendo o .env da própria pasta (Next, dotenv da API, Prisma CLI, Astro). scripts/copy-env.mjs (make env) gera esses arquivos a partir das seções: cria os que faltam e, nos existentes, só acrescenta as variáveis novas, sem alterar valores. FORCE=1 recria.
4. Só variáveis lidas pelo código e só valores de desenvolvimento (dev-only-…). Valores de produção ficam no Coolify.

Alternativas consideradas

• Um .env único carregado por todos os apps. Exigiria mudar como cada ferramenta lê o ambiente e misturaria chaves com valores diferentes por contexto (ex.: DATABASE_URL com localhost nos apps e postgres no compose).
• Manter um exemplo por pasta. É o que gerou a duplicação e o vazamento.

Consequências

• ➕ Um lugar para descobrir e documentar variáveis; a página Variáveis de ambiente segue as mesmas seções.
• ➕ Variável nova chega ao .env de todos com um make env, sem sobrescrever valores locais.
• ➖ O .env.example não deve ser copiado inteiro para um único .env (algumas chaves aparecem em mais de uma seção com valores diferentes); o cabeçalho do arquivo avisa.
• ➖ Variável nova no código precisa entrar na seção certa do exemplo; a auditoria pode ser feita comparando process.env.* com o arquivo.