Tutorial Node: Archivos .env y librería dotenv

Instalación de dotenv y uso de archivos .env

La gestión de configuraciones sensibles como claves de API, credenciales de bases de datos o URLs de servicios externos requiere un enfoque que mantenga estos valores fuera del código fuente. Los archivos .env proporcionan una solución estándar para almacenar estas variables de entorno de forma segura y organizada.

Instalación de la librería dotenv

Para trabajar con archivos .env en Node.js, necesitamos instalar la librería dotenv, que se encarga de cargar las variables desde el archivo hacia process.env. Esta instalación se realiza como dependencia de desarrollo:

npm install dotenv

Una vez instalada, podemos verificar que aparece en nuestro package.json dentro de las dependencias:

{
  "dependencies": {
    "dotenv": "^16.4.5"
  }
}

Creación y estructura del archivo .env

El archivo .env debe crearse en la raíz del proyecto, al mismo nivel que package.json. Este archivo utiliza una sintaxis simple de clave-valor sin espacios alrededor del signo igual:

# Configuración de base de datos
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mi_aplicacion
DB_USER=usuario_db
DB_PASSWORD=contraseña_secreta

# Configuración de API externa
API_KEY=abc123def456ghi789
API_URL=https://api.ejemplo.com/v1

# Configuración del servidor
PORT=3000
NODE_ENV=development

Es importante seguir las convenciones de nomenclatura: utilizar mayúsculas, separar palabras con guiones bajos y evitar espacios. Los comentarios se indican con el símbolo #.

Carga de variables con dotenv

Para que Node.js pueda acceder a las variables definidas en .env, debemos cargar dotenv al inicio de nuestra aplicación. Esto se hace importando y configurando la librería:

// Cargar dotenv al inicio del archivo principal
require('dotenv').config();

// Ahora podemos acceder a las variables de entorno
const dbHost = process.env.DB_HOST;
const dbPort = process.env.DB_PORT;
const apiKey = process.env.API_KEY;

console.log(`Conectando a la base de datos en ${dbHost}:${dbPort}`);
console.log(`Usando API key: ${apiKey ? '***configurada***' : 'no configurada'}`);

Uso práctico en una aplicación

Veamos un ejemplo completo de cómo integrar las variables de entorno en una aplicación Node.js que crea un servidor HTTP:

require('dotenv').config();
const http = require('http');

// Configuración desde variables de entorno
const PORT = process.env.PORT || 3000;
const NODE_ENV = process.env.NODE_ENV || 'development';
const API_URL = process.env.API_URL;

// Validar variables críticas
if (!API_URL) {
  console.error('Error: API_URL no está configurada en el archivo .env');
  process.exit(1);
}

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  
  const config = {
    environment: NODE_ENV,
    port: PORT,
    apiConfigured: !!API_URL
  };
  
  res.end(JSON.stringify(config, null, 2));
});

server.listen(PORT, () => {
  console.log(`Servidor ejecutándose en puerto ${PORT}`);
  console.log(`Entorno: ${NODE_ENV}`);
});

Configuración avanzada de dotenv

La librería dotenv ofrece opciones de configuración adicionales para casos específicos. Podemos especificar la ruta del archivo o manejar errores de carga:

// Configuración con opciones personalizadas
require('dotenv').config({
  path: './config/.env', // Ruta personalizada
  debug: process.env.DEBUG // Mostrar información de depuración
});

// Verificar si la carga fue exitosa
const result = require('dotenv').config();

if (result.error) {
  console.error('Error cargando archivo .env:', result.error);
} else {
  console.log('Variables de entorno cargadas correctamente');
}

Seguridad y buenas prácticas

El archivo .env debe excluirse del control de versiones añadiéndolo al .gitignore:

# Variables de entorno
.env
.env.local
.env.*.local

# Logs
*.log

# Dependencias
node_modules/

Para facilitar la configuración del proyecto, es recomendable crear un archivo .env.example que muestre la estructura necesaria sin valores reales:

# Archivo .env.example
DB_HOST=localhost
DB_PORT=5432
DB_NAME=nombre_base_datos
DB_USER=usuario
DB_PASSWORD=contraseña

API_KEY=tu_clave_api_aqui
API_URL=https://api.ejemplo.com

PORT=3000
NODE_ENV=development

Este enfoque permite que otros desarrolladores del equipo sepan qué variables configurar sin exponer información sensible en el repositorio.