Gestión de configuración de aplicaciones TypeScript: guía completa

Configuración de aplicaciones TypeScript: de lo simple a lo complejo

Cualquier aplicación moderna requiere una configuración flexible y segura. Ya sean claves de API, parámetros de conexión a la base de datos, puertos del servidor o banderas de funcionalidades — la configuración debe estar separada del código, ser fácil de leer y validarse en el momento del inicio. En el mundo de TypeScript, esta tarea tiene sus particularidades: la tipificación de la configuración proporciona autocompletado y previene errores en tiempo de ejecución. En este artículo, analizaremos las mejores prácticas, bibliotecas populares y herramientas para gestionar la configuración de aplicaciones TypeScript.

¿Por qué no deberías usar process.env directamente?

A primera vista, leer las variables de entorno a través de process.env parece una solución simple. Sin embargo, este enfoque tiene desventajas significativas:

• Falta de tipificación: todos los valores son cadenas, incluso si lógicamente son números o valores booleanos.
• Riesgo de errores tipográficos: es fácil escribir process.env.DB_HOTS en lugar de DB_HOST y obtener undefined.
• Falta de validación: si una variable obligatoria no está definida, la aplicación fallará en el momento más inesperado, no al iniciar.

Una configuración adecuada resuelve todos estos problemas.

La biblioteca dotenv y sus envoltorios para TypeScript

El estándar de facto para cargar archivos .env es la biblioteca dotenv. Para TypeScript, es conveniente usar dotenv-flow o dotenv-expand, que admiten múltiples entornos (development, staging, production).

// Instalación// npm install dotenv dotenv-expand

// config/env.tsimport dotenv from 'dotenv';import dotenvExpand from 'dotenv-expand';

const myEnv = dotenv.config({ path: `.env.${process.env.NODE_ENV || 'development'}` });dotenvExpand.expand(myEnv);

Después de llamar a esta función, todas las variables del archivo .env estarán disponibles a través de process.env, pero aún no tenemos tipos.

Validación de esquemas con Zod

Zod es una potente biblioteca para la validación declarativa de esquemas con soporte de primera clase para TypeScript. Es ideal para la configuración:

// config/schema.tsimport { z } from 'zod';

const envSchema = z.object({  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),  PORT: z.coerce.number().positive().default(3000),  DATABASE_URL: z.string().url(),  JWT_SECRET: z.string().min(32),  REDIS_HOST: z.string().default('localhost'),  REDIS_PORT: z.coerce.number().default(6379),  FEATURE_NEW_UI: z    .string()    .transform((val) => val === 'true')    .default('false'),});

export type EnvConfig = z.infer<typeof envSchema>;

Ahora podemos analizar y validar de forma segura el entorno al iniciar:

// config/index.tsimport { envSchema, EnvConfig } from './schema';

let config: EnvConfig;

export function loadConfig(): EnvConfig {  if (config) return config; // almacenamiento en caché

  const result = envSchema.safeParse(process.env);  if (!result.success) {    console.error('❌ Variables de entorno inválidas:', result.error.flatten().fieldErrors);    process.exit(1);  }  config = result.data;  return config;}

export function getConfig(): EnvConfig {  if (!config) throw new Error('Configuración no cargada. Llame a loadConfig() primero.');  return config;}

Biblioteca Conf para la gestión de configuración de aplicaciones

Si su aplicación requiere no solo leer, sino también escribir configuración (por ejemplo, ajustes de usuario, caché), preste atención a conf de Sindre Sorhus. Almacena datos en un archivo JSON y está completamente tipificada.

// Instalación// npm install conf

import Conf from 'conf';

interface AppConfig {  lastOp