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.

Para comenzar, conviene crear un archivo .env en la raíz del proyecto con la estructura deseada. Un ejemplo sencillo podría incluir variables como:

PORT=3000
DB_HOST=127.0.0.1
DB_USER=admin
DB_PASS=contraseñaSecreta

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.mjs
import { config } from "dotenv";
config();

export const {
    PORT = 3000,
    DB_HOST = "localhost",
    DB_USER = "root",
    DB_PASS = "123456789",
} = 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 { DB_PASS, DB_USER, PORT } from "./config.mjs";

console.log("Puerto:", PORT); // Puerto: 3000
console.log("Usuario DB:", DB_USER); // Usuario DB: admin
console.log("Contraseña DB:", DB_PASS); // Contraseña DB: contraseñaSecreta

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. Un ejemplo básico sería:

// 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
    DB_HOST = "localhost",
    DB_USER = "root",
    DB_PASS = "123456789",
} = 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 { DB_PASS, DB_USER, PORT } from "./config.mjs";

console.log("Puerto:", PORT); // "Puerto: 3000"
console.log("Usuario DB:", DB_USER); // "Usuario DB: admin"
console.log("Contraseña DB:", DB_PASS); // "Contraseña DB: contraseñaSecreta"

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
DB_HOST=127.0.0.1
DB_USER=admin-prod
DB_PASS=contraseñaSecreta-prod

Archivo .env.test:

PORT=3222
DB_HOST=127.0.0.1
DB_USER=admin-test
DB_PASS=contraseñaSecreta-test

Archivo .env (desarrollo por defecto):

PORT=3000
DB_HOST=localhost
DB_USER=root
DB_PASS=123456789

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.mjs
// Creamos un Map para almacenar los argumentos pasados por linea 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,
  DB_HOST,
  DB_USER,
  DB_PASS,
} = 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.mjs
import { config } from "dotenv";

// Creamos un Map para almacenar los argumentos pasados por linea 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,
  DB_HOST,
  DB_USER,
  DB_PASS,
} = 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"
  },
}

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.