Conceptos Básicos de Configuración

8 ejemplos para empezar con la Configuración para backends de Node.js: 6 básicos y 2 intermedios.

Prerrequisitos

npm install zod
npm install -D typescript@5.6 tsx dotenv

Node 24.18.0 lee process.env en tiempo de ejecución. Los valores de producción provienen de la plataforma (k8s, ECS, Fly.io), no de archivos en la imagen.

Ejemplos Básicos

1. Configuración de Doce Factores en un Solo Módulo

Todos los ajustes fluyen a través de una única exportación config.

// src/config.ts
import { z } from "zod";
 
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});
 
export const config = envSchema.parse(process.env);

• parse lanza un error al iniciar si falta DATABASE_URL: falla rápido, no en la primera solicitud
• Ningún otro archivo lee process.env directamente
• Las pruebas configuran process.env antes de importar config o usan importación dinámica después de la configuración

Relacionado: Validación de Zod y env-schema - ajustes tipados

2. Separa los Secretos de los No Secretos

Los secretos rotan con más frecuencia y necesitan ACLs más estrictas.

const envSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),           // secreto - cadena de conexión
  STRIPE_SECRET_KEY: z.string().min(1),     // secreto - clave API
  PUBLIC_WEB_URL: z.string().url(),         // no secreto - seguro en los logs
});

• Nunca registres DATABASE_URL o claves API; redáctalos en los serializadores de Pino
• Los no secretos pueden vivir en ConfigMaps; los secretos en Vault/SSM/k8s Secrets
• El mismo módulo Zod puede etiquetar campos para generadores de documentación

Relacionado: Administradores de Secretos - obtener al iniciar

3. .env Local Solo para Desarrollo

# .env.example (confirmado)
PORT=3000
DATABASE_URL=postgres://localhost:5432/app_dev
LOG_LEVEL=debug

// src/bootstrap-env.ts - solo importado desde la entrada de desarrollo
import { config as loadEnv } from "dotenv";
if (process.env.NODE_ENV !== "production") {
  loadEnv();
}

• Confirma .env.example, nunca .env
• CI y producción inyectan el entorno desde la plataforma
• dotenv es una devDependency cuando es posible

Relacionado: dotenv vs Inyección de Plataforma - local vs producción

4. Puerto Tipado y Entorno de Node

Evita los puertos tipados como cadenas en app.listen.

import { config } from "./config";
 
const app = express();
app.listen(config.PORT, () => {
  console.log(`escuchando en ${config.PORT} env=${config.NODE_ENV}`);
});

• z.coerce.number() acepta "3000" de las variables de entorno de cadena de k8s
• Comporta el comportamiento de la rama en config.NODE_ENV, no en process.env.NODE_ENV dispersos
• El entorno test usa una URL de base de datos en memoria de los secretos de CI

5. Alternadores de Funciones como Configuración (Estático)

Banderas booleanas del entorno para interruptores de apagado simples.

const envSchema = z.object({
  FEATURE_NEW_CHECKOUT: z
    .enum(["true", "false"])
    .default("false")
    .transform((v) => v === "true"),
});

• Las banderas de entorno estáticas requieren un nuevo despliegue para cambiar; está bien para alternadores poco frecuentes
• Para banderas por usuario, usa un proveedor en tiempo de ejecución (LaunchDarkly, Unleash)
• Documenta cada bandera en .env.example con el propietario y la fecha de eliminación

Relacionado: Banderas de Funciones y Alternadores en Tiempo de Ejecución - banderas dinámicas

6. Tiempos de Espera y Tamaños de Pool Configurables

El ajuste operacional pertenece a la configuración, no a números mágicos codificados.

const envSchema = z.object({
  HTTP_TIMEOUT_MS: z.coerce.number().default(30_000),
  DB_POOL_MAX: z.coerce.number().default(10),
});

• Los valores predeterminados en el esquema Zod documentan líneas base de producción sensatas
• Anula en staging para ensayar modos de fallo
• Alerta cuando los valores de producción se desvían de los rangos documentados

Ejemplos Intermedios

7. Singleton de Configuración Perezosa con Anulación de Prueba

let cached: AppConfig | undefined;
 
export function loadConfig(env = process.env): AppConfig {
  if (!cached) cached = envSchema.parse(env);
  return cached;
}
 
export function resetConfigForTests() {
  cached = undefined;
}

• Las pruebas llaman a resetConfigForTests() entre casos
• La producción importa loadConfig() una vez al iniciar
• Evita analizar el entorno en cada importación durante la recarga en caliente

8. Valida Campos Relacionados con .refine

const envSchema = z
  .object({
    REDIS_URL: z.string().url().optional(),
    CACHE_ENABLED: z.enum(["true", "false"]).transform((v) => v === "true"),
  })
  .refine((e) => !e.CACHE_ENABLED || e.REDIS_URL, {
    message: "REDIS_URL requerido cuando CACHE_ENABLED=true",
  });

• Las reglas entre campos detectan entornos de staging mal configurados al iniciar
• Los mensajes de error aparecen en los logs de despliegue de CI antes de que se enrute el tráfico
• Combina con Mejores Prácticas de Configuración para estándares de equipo

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.