Estructura de proyecto, env vars y configuracion

Estructura de proyecto, variables de entorno y configuración

Una API que funciona en tu máquina pero falla en producción casi siempre tiene un problema de configuración. La regla de oro del enfoque Twelve-Factor es separar la configuración del código: lo que cambia entre tu portátil, el servidor de pruebas y producción (puertos, URLs de base de datos, claves) vive en el entorno, nunca dentro de los archivos versionados en Git.

Una estructura sencilla y escalable

mi-api/

  src/

    config.js        # lee y valida process.env

    app.js           # crea la app Express (sin escuchar)

    server.js        # arranca y escucha en el puerto

    routes/

    middleware/

    db/

  .env               # NUNCA se sube a Git

  .env.example       # plantilla que sí se versiona

  .gitignore

Separar app.js (la configuración de Express) de server.js (el listen) te permite importar la app en tus tests sin abrir un puerto real.

Centraliza y valida la configuración

// src/config.js

import 'dotenv/config';



function required(name) {

  const value = process.env[name];

  if (!value) throw new Error(`Falta la variable de entorno ${name}`);

  return value;

}



export const config = {

  port: Number(process.env.PORT ?? 3000),

  databaseUrl: required('DATABASE_URL'),

  nodeEnv: process.env.NODE_ENV ?? 'development',

};

Falla rápido, no a medias

Si falta DATABASE_URL, es mejor que la app no arranque a que lance un error críptico en la primera consulta de un usuario real. Validar al inicio convierte un fallo silencioso en un error claro y temprano.

Ejercicio práctico