Tutorial Node: Variables de entorno

Qué es una variable de entorno y cómo se crea

Las variables de entorno son valores dinámicos que el sistema operativo pone a disposición de los procesos en ejecución. Funcionan como un mecanismo de configuración que permite que las aplicaciones accedan a información específica del entorno donde se ejecutan, sin necesidad de codificar estos valores directamente en el código fuente.

En el contexto de Node.js, las variables de entorno resultan especialmente útiles para configurar aspectos críticos de nuestras aplicaciones como puertos de servidor, cadenas de conexión a bases de datos, claves API o cualquier valor que pueda cambiar entre diferentes entornos de ejecución (desarrollo, pruebas, producción).

Creación de variables de entorno en diferentes sistemas

La forma de crear variables de entorno varía según el sistema operativo que utilicemos. En sistemas Unix y Linux (incluyendo macOS), podemos definir variables de entorno directamente desde la terminal:

export PORT=3000
export DATABASE_URL="mongodb://localhost:27017/miapp"

En Windows, utilizamos el comando set en el símbolo del sistema:

set PORT=3000
set DATABASE_URL=mongodb://localhost:27017/miapp

O en PowerShell:

$env:PORT = "3000"
$env:DATABASE_URL = "mongodb://localhost:27017/miapp"

Variables de entorno temporales vs permanentes

Las variables definidas con los comandos anteriores son temporales y solo existen durante la sesión actual de la terminal. Para crear variables permanentes, necesitamos modificar los archivos de configuración del sistema.

En sistemas Unix/Linux, podemos agregar las variables al archivo ~/.bashrc, ~/.zshrc o ~/.profile:

# Agregar al final del archivo ~/.bashrc
export NODE_ENV=production
export API_KEY=mi_clave_secreta

En Windows, podemos usar la interfaz gráfica del sistema o el comando setx para variables permanentes:

setx PORT "3000"
setx NODE_ENV "production"

Definición de variables al ejecutar Node.js

Una práctica común es definir variables de entorno directamente al ejecutar nuestra aplicación Node.js. Esto resulta especialmente útil durante el desarrollo:

PORT=8080 NODE_ENV=development node app.js

En Windows:

set PORT=8080 && set NODE_ENV=development && node app.js

Este enfoque permite configurar variables específicas para cada ejecución sin modificar la configuración global del sistema.

Variables de entorno predefinidas del sistema

El sistema operativo ya proporciona numerosas variables predefinidas que podemos utilizar en nuestras aplicaciones Node.js. Algunas de las más comunes incluyen:

• PATH: Rutas donde el sistema busca ejecutables
• HOME (Unix/Linux) o USERPROFILE (Windows): Directorio home del usuario
• USER o USERNAME: Nombre del usuario actual
• PWD: Directorio de trabajo actual

Estas variables nos permiten crear aplicaciones que se adapten automáticamente al entorno donde se ejecutan, mejorando la portabilidad del código.

Convenciones de nomenclatura

Existe una convención ampliamente adoptada para nombrar variables de entorno. Se recomienda usar letras mayúsculas y separar palabras con guiones bajos:

export DATABASE_HOST=localhost
export DATABASE_PORT=5432
export API_SECRET_KEY=mi_clave_ultra_secreta
export MAX_CONNECTIONS=100

Esta convención facilita la identificación de variables de entorno en el código y mejora la legibilidad, especialmente cuando trabajamos con equipos de desarrollo.

process.env básico

El objeto process.env es la interfaz principal que Node.js proporciona para acceder a las variables de entorno desde nuestro código JavaScript. Este objeto global contiene todas las variables de entorno disponibles en el momento de la ejecución, permitiendo que nuestras aplicaciones lean y utilicen esta información de configuración.

Acceso a variables de entorno

Para acceder a una variable de entorno específica, utilizamos la sintaxis de objeto estándar de JavaScript. Si hemos definido una variable llamada PORT, podemos acceder a ella de la siguiente manera:

console.log(process.env.PORT); // Muestra el valor de la variable PORT
console.log(process.env.NODE_ENV); // Muestra el valor de NODE_ENV

Es importante recordar que todas las variables de entorno se almacenan como cadenas de texto, independientemente del tipo de dato que representen. Si necesitamos trabajar con números, debemos realizar la conversión correspondiente:

const port = parseInt(process.env.PORT) || 3000;
const maxConnections = Number(process.env.MAX_CONNECTIONS) || 10;

Manejo de variables no definidas

Cuando intentamos acceder a una variable de entorno que no existe, process.env devuelve undefined. Esta característica nos permite implementar valores por defecto utilizando el operador OR lógico:

const databaseUrl = process.env.DATABASE_URL || 'mongodb://localhost:27017/default';
const apiTimeout = process.env.API_TIMEOUT || '5000';
const debugMode = process.env.DEBUG === 'true'; // Conversión a booleano

Ejemplo práctico: servidor HTTP configurable

Veamos cómo utilizar process.env para crear un servidor HTTP que se adapte a diferentes configuraciones de entorno:

const http = require('http');

// Configuración desde variables de entorno
const port = process.env.PORT || 3000;
const host = process.env.HOST || 'localhost';
const environment = process.env.NODE_ENV || 'development';

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  
  const response = {
    message: 'Servidor funcionando correctamente',
    environment: environment,
    timestamp: new Date().toISOString()
  };
  
  res.end(JSON.stringify(response, null, 2));
});

server.listen(port, host, () => {
  console.log(`Servidor ejecutándose en http://${host}:${port}`);
  console.log(`Entorno: ${environment}`);
});

Para ejecutar este servidor con diferentes configuraciones:

# Configuración de desarrollo
NODE_ENV=development PORT=8080 node servidor.js

# Configuración de producción
NODE_ENV=production PORT=80 HOST=0.0.0.0 node servidor.js

Listado de todas las variables disponibles

Podemos inspeccionar todas las variables de entorno disponibles accediendo directamente al objeto process.env:

// Mostrar todas las variables de entorno
console.log('Variables de entorno disponibles:');
console.log(process.env);

// Filtrar variables específicas de nuestra aplicación
const appVars = {};
for (const [key, value] of Object.entries(process.env)) {
  if (key.startsWith('APP_') || key.startsWith('DATABASE_')) {
    appVars[key] = value;
  }
}
console.log('Variables de la aplicación:', appVars);

Validación de variables requeridas

En aplicaciones profesionales, es común validar la presencia de variables de entorno críticas al inicio de la aplicación:

// Lista de variables requeridas
const requiredVars = ['DATABASE_URL', 'API_SECRET_KEY', 'JWT_SECRET'];

// Verificar que todas las variables estén definidas
const missingVars = requiredVars.filter(varName => !process.env[varName]);

if (missingVars.length > 0) {
  console.error('Error: Variables de entorno requeridas no encontradas:');
  missingVars.forEach(varName => console.error(`- ${varName}`));
  process.exit(1); // Terminar la aplicación con código de error
}

console.log('Todas las variables de entorno requeridas están configuradas');

Configuración condicional basada en el entorno

Las variables de entorno nos permiten implementar lógica condicional para adaptar el comportamiento de nuestra aplicación según el entorno de ejecución:

const isDevelopment = process.env.NODE_ENV === 'development';
const isProduction = process.env.NODE_ENV === 'production';

// Configuración de logging
const logLevel = isDevelopment ? 'debug' : 'error';
const enableDetailedLogs = process.env.DETAILED_LOGS === 'true' || isDevelopment;

// Configuración de base de datos
const dbConfig = {
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT) || 5432,
  ssl: isProduction, // SSL solo en producción
  poolSize: isProduction ? 20 : 5
};

console.log(`Configuración para entorno: ${process.env.NODE_ENV}`);
console.log(`Nivel de logging: ${logLevel}`);
console.log(`Configuración de BD:`, dbConfig);

Esta aproximación nos permite mantener un código único que se comporta de manera diferente según las variables de entorno configuradas, facilitando el despliegue en múltiples entornos sin modificar el código fuente.