dotenv-diff

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

Porquê o dotenv-diff?

• Garantir que todas as variáveis de ambiente necessárias estão definidas
• Detetar variáveis em falta ou mal configuradas
• Melhorar a colaboração mantendo as equipas alinhadas quanto às variáveis necessárias
• Reduzir o risco de submeter dados sensíveis
• Escalar facilmente para monorepos e configurações multi-ambiente

Como Funciona

→ Consulte a Documentação de Capacidades para detalhes sobre o que o scanner verifica e como funciona.

Configuração (--init)

Gere um ficheiro de configuração padrão:

dotenv-diff --init

→ Consulte a Documentação de Configuração para mais detalhes.

Git hooks e Integração CI/CD

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.

Avisos Específicos de Frameworks

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.

Escrever um bom .env.example

Um .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

Avisos de Deriva

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.

Avisos de Expiração

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.

Comentários de Ignoração

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.

Suprimir avisos existentes (--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.

Explicar uma variável (--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.

Suporte para monorepos

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á:

• Verificar a aplicação atual
• Incluir pacotes partilhados
• Ignorar variáveis usadas apenas em ambientes específicos

Códigos de Saída

• 0 → Sem erros
• 1 → Erros encontrados (ou avisos em modo estrito)

Documentação

→ Consulte a Documentação do dotenv-diff para documentação completa

Contribuir

Issues e pull requests são bem-vindos.
→ Consulte CONTRIBUTING para detalhes.

Agradecimentos a estas pessoas fantásticas por contribuírem para este projeto:

Licença

Licenciado sob a licença MIT.

Criado por chrilleweb