Mejores Prácticas para la Configuración de Proyectos

Estándares para repositorios de servicios Node que se integran rápidamente, se construyen en CI y se despliegan de forma predecible.

Cómo Usar Esta Lista

• Aplícala al crear repositorios a partir de plantillas o generadores.
• Revísala durante las revisiones de arquitectura antes de añadir un segundo elemento desplegable.
• Haz cumplir el diseño y los scripts a través de la CI de la plantilla, no mediante convenciones informales.

A - Diseño del Repositorio

• Usa src/ para el código de tiempo de ejecución y una ubicación de prueba dedicada. Elige test/ o *.test.ts colocados juntos, no ambos.
• Un elemento desplegable principal por carpeta de aplicación en monorepos. apps/billing-api se asigna a una imagen de contenedor.
• Mantén la configuración en la raíz del repositorio o en la raíz de la aplicación de forma consistente. La detectabilidad de tsconfig, ESLint y Dockerfile es importante.
• Haz commit de .env.example, nunca de secretos. Documenta cada variable requerida con valores predeterminados seguros.
• Incluye rutas health (y opcionalmente ready) desde el primer día. Los balanceadores de carga y los orquestadores las necesitan.

B - TypeScript y Scripts

• Divide tsconfig.json y tsconfig.build.json. Verifica el tipo de las pruebas; emite solo src/ a dist/.
• Usa la resolución de módulos NodeNext en Node 24. Coincide con el comportamiento de import de ESM en producción.
• Exporta createApp() (o equivalente) desde los servidores. Permite pruebas de integración HTTP sin vincular puertos.
• Scripts: dev, build, start, test, typecheck. Los mismos comandos localmente y en CI.
• Ejecuta start de producción contra JS compilado. No tsx en contenedores.

C - Docker y Tiempo de Ejecución

• Fija el parche de Node en Dockerfile (node:24.18.0-alpine). Alinéalo con engines en package.json.
• Compilaciones multi-etapa: dependencias, compilación, tiempo de ejecución. La imagen de producción excluye TypeScript y devDependencies.
• Copia el archivo de bloqueo antes del código fuente para la caché de capas. La capa npm ci se reconstruye solo cuando cambian las dependencias.
• Establece NODE_ENV=production en la etapa de tiempo de ejecución. Los frameworks y la verbosidad de los logs dependen de ello.
• Documenta el puerto expuesto y la ruta de salud en el README. Coincide con las sondas de K8s y los archivos compose.

D - Monorepo y Scaffolding

• Código compartido en packages/, elementos desplegables en apps/. Las aplicaciones nunca importan aplicaciones hermanas directamente.
• Mantén un repositorio de plantillas interno con CI. Los nuevos servicios heredan los pines actuales de Express/Fastify/Nest.
• Usa Turborepo o Nx cuando 3 o más paquetes necesiten orquestación. Los scripts de npm simples dejan de escalar.
• Filtra por ruta los despliegues de CI por servicio. Los cambios de API no relacionados no deben volver a desplegar la facturación.
• Versiona el paquete de contratos internos con disciplina de cambios disruptivos. Los cambios de esquema de Zod afectan a múltiples aplicaciones.

E - Documentación y Gobernanza

• Inicio rápido del README: npm ci, copia de .env, npm run dev. Tres pasos para ejecutar el servidor.
• Registra la elección del framework en ADR para nuevos servicios. Express vs Fastify vs Nest no es arbitrario por repositorio.
• Añade una prueba de ejemplo en el scaffold. La CI nunca se envía con un npm test vacío que pasa trivialmente.
• .gitignore cubre node_modules, dist, .env, coverage. Evita commits accidentales.
• Renombra y limpia los marcadores de posición de la plantilla antes del primer despliegue. Los nombres de servicio predeterminados se propagan a las métricas y los logs.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Configuración de Proyectos - ejemplos de diseño
• Scaffolding de APIs - plantillas y CLIs
• Monorepo de Múltiples Servicios - reglas de aplicación vs paquete

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.