Tutorial Node: Configuración y variables de entorno

Uso de archivos .env con la biblioteca dotenv

El uso de archivos .env facilita la gestión de variables sensibles, como credenciales de bases de datos, claves de API u otras configuraciones, separándolas del código fuente. Esto mejora la seguridad y la claridad de la arquitectura, al mantener la información confidencial fuera del repositorio principal.

Importante: Antes de comenzar, es fundamental entender que los archivos .env NUNCA deben incluirse en el control de versiones. Asegúrate de agregar .env a tu archivo .gitignore para evitar exponer credenciales sensibles en repositorios públicos o compartidos.

Las variables de entorno evitan que credenciales sensibles como contraseñas de base de datos, claves JWT o rutas de archivos queden expuestas directamente en el código fuente, lo que podría comprometer la seguridad si el repositorio es accedido por personas no autorizadas.

Para comenzar, conviene crear un archivo .env en la raíz del proyecto con la estructura deseada. Un ejemplo contextualizado para una aplicación web podría incluir variables como:

PORT=3000
DATABASE_URL=mysql://user:pass@localhost:3306/employees_db
JWT_SECRET=tu_clave_secreta_muy_larga_y_segura_aqui
UPLOAD_PATH=./uploads
BCRYPT_ROUNDS=10

Estas líneas quedarán disponibles en tiempo de ejecución sin quedar expuestas directamente en el código fuente.

La instalación de la biblioteca dotenv se realiza mediante el siguiente comando:

npm install dotenv

Posteriormente, se importa y configura al inicio del punto de entrada del programa. Un ejemplo básico sería:

// config/config.mjs
import { config } from "dotenv";
config();

export const {
    PORT = 3000,
    DATABASE_URL = "mysql://root:123456789@localhost:3306/test_db",
    JWT_SECRET = "clave_por_defecto_desarrollo",
    UPLOAD_PATH = "./uploads",
    BCRYPT_ROUNDS = 10,
} = process.env;

Una vez establecido el scripts de configuración, podremos usar las variables de entornos en cualquier lugar de nuestro proyecto:

// index.mjs
import { DATABASE_URL, JWT_SECRET, PORT } from "./config/config.mjs";

console.log("Puerto:", PORT); // Puerto: 3000
console.log("Base de datos:", DATABASE_URL); // Base de datos: mysql://user:pass@localhost:3306/employees_db
console.log("JWT configurado:", JWT_SECRET ? "Sí" : "No"); // JWT configurado: Sí

El contenido de process.env se fundamenta en las variables definidas dentro de .env, permitiendo reemplazar valores en diferentes entornos sin modificar el código principal. Así se evitan malas prácticas como incrustar valores estáticos de conexión en los ficheros de producción.

Manejo de variables de entorno de forma nativa

Aviso: El uso de variables de entorno con métodos nativos de Node.js está disponible únicamente a partir de la versión 22.

Node.js ofrece un método nativo para manejar variables de entorno, eliminando la necesidad de bibliotecas externas en el proyecto. Este enfoque no solo simplifica el acceso a configuraciones sensibles como puertos y credenciales, sino que también permite un flujo de despliegue más coherente en proyectos de cualquier escala.

La funcionalidad se centra en el método process.loadEnvFile(), que carga archivos .env con formato clave-valor y agrega automáticamente las variables al objeto process.env. Esto asegura que las variables estén disponibles en cualquier módulo del proyecto.

Para garantizar que las variables de entorno estén accesibles en toda la aplicación, es recomendable configurar su carga al inicio del programa. En la estructura de carpetas organizada, esto quedaría así:

proyecto/
├── controllers/
├── models/
├── services/
├── config/
│   └── config.js      // ← Configuración de variables
├── .env               // ← Variables de desarrollo
├── .env.prod          // ← Variables de producción
├── .gitignore         // ← Incluir .env* aquí
└── server.js

Un ejemplo básico de configuración sería:

// config/config.mjs
process.loadEnvFile();

export const {
    PORT = 3000, // En caso de que no exista PORT en el archivo ".env" el valor por defecto será 3000
    DATABASE_URL = "mysql://root:123456789@localhost:3306/test_db",
    JWT_SECRET = "clave_por_defecto_desarrollo",
    UPLOAD_PATH = "./uploads",
    BCRYPT_ROUNDS = 10,
} = process.env;

Una vez configurado este script, las variables de entorno estarán disponibles para su uso en cualquier módulo del proyecto:

// index.mjs
import { DATABASE_URL, JWT_SECRET, PORT } from "./config/config.mjs";

console.log("Puerto:", PORT); // "Puerto: 3000"
console.log("Base de datos:", DATABASE_URL); // "Base de datos: mysql://user:pass@localhost:3306/employees_db"
console.log("JWT configurado:", JWT_SECRET ? "Sí" : "No"); // "JWT configurado: Sí"

Este enfoque centraliza y facilita la configuración de variables de entorno, asegurando su disponibilidad desde el inicio de la aplicación y simplificando su uso en cualquier parte del proyecto.

Configuración para distintos entornos

Cuando trabajas con múltiples entornos, como desarrollo, producción o pruebas, es importante definir configuraciones específicas en archivos separados para cada entorno. Por ejemplo:

Archivo .env.prod:

PORT=3360
DATABASE_URL=mysql://admin-prod:contraseñaSecreta@db-server:3306/employees_prod
JWT_SECRET=clave_ultra_secreta_produccion_con_256_caracteres_minimo
UPLOAD_PATH=/var/www/uploads
BCRYPT_ROUNDS=12

Archivo .env.test:

PORT=3222
DATABASE_URL=mysql://admin-test:contraseñaTest@localhost:3306/employees_test
JWT_SECRET=clave_secreta_testing_diferente_a_produccion
UPLOAD_PATH=./test-uploads
BCRYPT_ROUNDS=8

Archivo .env (desarrollo por defecto):

PORT=3000
DATABASE_URL=mysql://root:123456789@localhost:3306/employees_dev
JWT_SECRET=clave_desarrollo_local_no_segura
UPLOAD_PATH=./uploads
BCRYPT_ROUNDS=10

Con estos archivos, puedes configurar tu aplicación para cargar automáticamente el archivo correspondiente según el entorno en que se ejecute.

Configuración nativa con process.loadEnvFile

Node.js, a partir de la versión 22, permite manejar estas configuraciones de manera nativa utilizando process.loadEnvFile(). Puedes configurar tu aplicación de la siguiente forma:

// config/config.mjs
// Creamos un Map para almacenar los argumentos pasados por línea de comandos
const args = process.argv.slice(2).reduce((acc, arg) => {
    const [key, value] = arg.split("=");
    return acc.set(key.replace("--", ""), value);
}, new Map());

const ENVIRONMENTS = {
  production: ".env.prod",
  test: ".env.test",
  development: ".env", // Variable de entorno por defecto
};

// Determina el archivo de entorno a cargar según el argumento --env
const path = ENVIRONMENTS[args.get("env")];
process.loadEnvFile(path);

export const {
  PORT,
  DATABASE_URL,
  JWT_SECRET,
  UPLOAD_PATH,
  BCRYPT_ROUNDS,
} = process.env;

Al ejecutar tu aplicación, asegúrate de establecer el argumento --env para cargar el archivo adecuado. Por ejemplo:

node index.mjs --env=production

Configuración con dotenv

Si prefieres usar la biblioteca dotenv, puedes lograr la misma funcionalidad con la siguiente configuración:

// config/config.mjs
import { config } from "dotenv";

// Creamos un Map para almacenar los argumentos pasados por línea de comandos
const args = process.argv.slice(2).reduce((acc, arg) => {
    const [key, value] = arg.split("=");
    return acc.set(key.replace("--", ""), value);
}, new Map());

const ENVIRONMENTS = {
  production: ".env.prod",
  test: ".env.test",
  development: ".env", // Variable de entorno por defecto
};

// Determina el archivo de entorno a cargar según el argumento --env
const path = ENVIRONMENTS[args.get("env")];
config({ path });

export const {
  PORT,
  DATABASE_URL,
  JWT_SECRET,
  UPLOAD_PATH,
  BCRYPT_ROUNDS,
} = process.env;

Del mismo modo, ejecuta tu aplicación configurando el argumento --env para cargar el entorno adecuado:

node index.mjs --env=test

Por último: configuración del package.json

Para facilitar la ejecución de la aplicación en distintos entornos, puedes agregar scripts personalizados en el archivo package.json. Aquí tienes un ejemplo:

{
  "scripts": {
    "start": "node index.mjs",
    "start:prod": "node index.mjs --env=production",
    "start:test": "node index.mjs --env=test",
    "dev": "node index.mjs --env=development"
  }
}

Importante para seguridad: Asegúrate de que tu archivo .gitignore incluya todas las variantes de archivos de entorno:

# Variables de entorno - NUNCA subir al repositorio
.env
.env.local
.env.prod
.env.test
.env.*.local

# Directorio de archivos subidos
uploads/
test-uploads/

Este archivo package.json te permitirá ejecutar tu aplicación en los distintos entornos de forma sencilla y organizada, utilizando los comando npm run start, npm run start:prod y otros que se hallan configurado, completando así un flujo robusto para el manejo de variables de entorno.