chrilleweb/dotenv-diffValidar o uso de variáveis de ambiente na base de código
Digitalize o seu código para detetar todas as referências a variáveis de ambiente. Ajuda-o a detetar variáveis em falta, não utilizadas, duplicadas ou mal utilizadas, antes de causarem erros em tempo de execução.
Suporte de primeira classe para SvelteKit, Next.js e Nuxt. Também funciona bem em projetos modernos de JavaScript/TypeScript e frameworks como Node.js e Vue — ou em qualquer outra configuração onde pretenda uma comparação fiável de ficheiros .env.
✨ Destaque em awesome-cli-apps - Uma lista selecionada de aplicações CLI fantásticas
→ Consulte a Documentação de Capacidades para detalhes sobre o que o scanner verifica e como funciona.
--init)Gere um ficheiro de configuração padrão:
dotenv-diff --init
→ Consulte a Documentação de Configuração para mais detalhes.
Integre facilmente o dotenv-diff nos seus Git hooks ou pipelines CI/CD para impor consistência nas variáveis de ambiente.
→ Consulte a Documentação de Git Hooks para mais detalhes.
Em projetos SvelteKit, Next.js e Nuxt, o dotenv-diff deteta a utilização incorreta de variáveis de ambiente específicas do framework.
▸ Problemas de framework (SvelteKit)
──────────────────────────────────────────────────────────────────────
PUBLIC_API_URL $env/dynamic/private
as variáveis não devem
começar com "PUBLIC_"
src/routes/+page.server.ts:3
──────────────────────────────────────────────────────────────────────
→ Consulte a Documentação de Frameworks para mais detalhes.
.env.exampleUm .env.example escrito de forma a ser mais fácil de entender para novos contribuidores da equipa:
# Ambiente Node (development, production, etc.)
# @optional
NODE_ENV=development
# A URL da API pública é usada para chamar o nosso backend
PUBLIC_API_URL=http://localhost:3000
# Token temporário para o sandbox da API de parceiros — peça um novo à equipa de integrações
# @expire 2027-03-31
PARTNER_API_TOKEN=
→ Leia mais: Escrever um Bom .env.example
Uma verificação compara o seu código com um único ficheiro — portanto, qualquer chave que adicione ao .env e se esqueça no .env.example fica invisível até um novo contribuidor clonar o repositório. Os avisos de deriva detetam exatamente isso:
▸ Deriva entre .env e .env.example
──────────────────────────────────────────────────────────────────────
STRIPE_SECRET não documentado no .env.example
──────────────────────────────────────────────────────────────────────
Ativado por padrão; desative com --no-drift-warnings.
→ Consulte Avisos de Deriva para mais detalhes.
Adicione metadados de expiração às suas variáveis de ambiente para receber avisos quando estiverem prestes a expirar. Por exemplo, no seu ficheiro .env:
# @expire 2025-12-31
API_TOKEN=
→ Consulte a Documentação de Expiração para mais detalhes.
Pode ignorar avisos específicos de variáveis de ambiente adicionando comentários no seu código. Por exemplo:
const apiKey = process.env.API_KEY; // dotenv-diff-ignore
Isto é útil quando sabe que um aviso específico é seguro no seu código-fonte.
→ Consulte a Documentação de Comentários de Ignoração para mais detalhes.
--baseline)Adote o dotenv-diff em projetos que já têm avisos conhecidos, registando o estado atual num ficheiro de baseline. Execuções futuras apenas reportarão problemas recém-introduzidos:
dotenv-diff --baseline
→ Consulte a Documentação de Baseline para mais detalhes.
--explain)Inspecione uma variável de ambiente específica para ver onde está definida, onde é usada no código e o seu estado geral:
dotenv-diff --explain DATABASE_URL
→ Consulte a Documentação de --explain para mais detalhes.
Em monorepos com múltiplas aplicações e pacotes, pode incluir pastas partilhadas:
{
"scripts": {
"dotenv-diff": "dotenv-diff --example .env.example --include-files '../../packages/**/*' --ignore VITE_MODE"
}
}
→ Consulte a Documentação de Monorepo para mais detalhes.
Isto irá:
0 → Sem erros1 → Erros encontrados (ou avisos em modo estrito)→ Consulte a Documentação do dotenv-diff para documentação completa
Issues e pull requests são bem-vindos.
→ Consulte CONTRIBUTING para detalhes.
Agradecimentos a estas pessoas fantásticas por contribuírem para este projeto:
Licenciado sob a licença MIT.
Criado por chrilleweb