dotenv-diff

Escanea tu código para detectar cada referencia a variables de entorno. Te ayuda a detectar variables faltantes, sin usar, duplicadas o mal utilizadas antes de que causen errores en tiempo de ejecución.

Soporte de primera clase para SvelteKit, Next.js y Nuxt. También funciona bien en proyectos modernos de JavaScript/TypeScript y frameworks como Node.js y Vue — o en cualquier otro entorno donde necesites una comparación fiable de archivos .env.

✨ Destacado en awesome-cli-apps - Una lista curada de aplicaciones CLI impresionantes

Demo

¿Por qué dotenv-diff?

Garantiza que todas las variables de entorno requeridas estén definidas
Detecta variables faltantes o mal configuradas
Mejora la colaboración manteniendo a los equipos alineados sobre las variables requeridas
Reduce el riesgo de comprometer datos sensibles
Escala fácilmente para monorepos y configuraciones multi-entorno

Cómo Funciona

→ Consulta la Documentación de Capacidades para conocer los detalles sobre qué comprueba el escáner y cómo funciona.

Configuración (`--init`)

Genera un archivo de configuración predeterminado:

dotenv-diff --init

→ Consulta la Documentación de Configuración para más detalles.

Hooks de Git e Integración CI/CD

Integra fácilmente dotenv-diff en tus hooks de Git o pipelines de CI/CD para garantizar la consistencia de las variables de entorno.

→ Consulta la Documentación de Git Hooks para más detalles.

Advertencias Específicas de Frameworks

En proyectos de SvelteKit, Next.js y Nuxt, dotenv-diff detecta el mal uso de variables de entorno específico del framework.

▸ Problemas del framework (SvelteKit)
──────────────────────────────────────────────────────────────────────
PUBLIC_API_URL              $env/dynamic/private
                            las variables no deben
                            comenzar con "PUBLIC_"
                            src/routes/+page.server.ts:3
──────────────────────────────────────────────────────────────────────

→ Consulta la Documentación de Frameworks para más detalles.

Escribir un buen `.env.example`

Un .env.example escrito de forma que sea más fácil de entender para los nuevos colaboradores del equipo:

# Entorno de Node (development, production, etc.)
# @optional
NODE_ENV=development

# La URL pública de la API se usa para llamar a nuestro backend
PUBLIC_API_URL=http://localhost:3000

# Token temporal para el sandbox de la API del socio — pide uno nuevo al equipo de integraciones
# @expire 2027-03-31
PARTNER_API_TOKEN=

→ Lee más: Escribir un buen .env.example

Advertencias de Deriva

Un escaneo compara tu código contra un solo archivo — por lo que cualquier clave que añadas a .env y olvides en .env.example es invisible hasta que un nuevo colaborador clona el repositorio. Las advertencias de deriva detectan exactamente eso:

▸ Deriva entre .env y .env.example
──────────────────────────────────────────────────────────────────────
STRIPE_SECRET               no documentado en .env.example
──────────────────────────────────────────────────────────────────────

Activado por defecto; desactívalo con --no-drift-warnings.

→ Consulta Advertencias de Deriva para más detalles.

Advertencias de Expiración

Añade metadatos de expiración a tus variables de entorno para recibir advertencias cuando estén a punto de expirar. Por ejemplo, en tu archivo .env:

# @expire 2025-12-31
API_TOKEN=

→ Consulta la Documentación de Expiración para más detalles.

Comentarios de Ignorar

Puedes ignorar advertencias específicas de variables de entorno añadiendo comentarios en tu código. Por ejemplo:

const apiKey = process.env.API_KEY; // dotenv-diff-ignore

Esto es útil cuando sabes que una advertencia específica es segura en tu código fuente.

→ Consulta la Documentación de Comentarios de Ignorar para más detalles.

Suprimir advertencias existentes (`--baseline`)

Adopta dotenv-diff en proyectos que ya tienen advertencias conocidas registrando el estado actual en un archivo de referencia. Las ejecuciones futuras solo reportarán problemas recién introducidos:

dotenv-diff --baseline

→ Consulta la Documentación de Baseline para más detalles.

Explicar una variable (`--explain`)

Inspecciona una variable de entorno específica para ver dónde está definida, dónde se usa en el código y su estado general:

dotenv-diff --explain DATABASE_URL

→ Consulta la Documentación de --explain para más detalles.

Soporte para monorepos

En monorepos con múltiples aplicaciones y paquetes, puedes incluir carpetas compartidas:

{
  "scripts": {
    "dotenv-diff": "dotenv-diff --example .env.example --include-files '../../packages/**/*' --ignore VITE_MODE"
  }
}

→ Consulta la Documentación de Monorepo para más detalles.

Esto:

Escaneará la aplicación actual
Incluirá paquetes compartidos
Ignorará variables usadas solo en entornos específicos

Códigos de Salida

0 → Sin errores
1 → Errores encontrados (o advertencias en modo estricto)

Documentación

→ Consulta la Documentación de dotenv-diff para la documentación completa

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas.
→ Consulta CONTRIBUTING para más detalles.

Gracias a estas increíbles personas por contribuir a este proyecto:

Licencia

Licenciado bajo la licencia MIT.

Creado por chrilleweb

dotenv-diff [email protected]

Categorías