Scaffolding APIs

El scaffolding crea un punto de partida consistente para que cada nuevo servicio tenga el mismo diseño, scripts y controles de calidad.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

mkdir orders-api && cd orders-api
npm init -y
npm install express@5
npm install -D typescript@5.6 tsx @types/node @types/express eslint
npx --yes @nestjs/cli new orders-api --package-manager npm --strict

Cuándo usarlo:

• Para iniciar un servicio HTTP nuevo.
• Para estandarizar el diseño de carpetas y los hooks de CI en toda la organización.
• Para evitar copiar y pegar de un repositorio antiguo con dependencias obsoletas.

Ejemplo práctico

# 1. Plantilla de la organización (preferida para equipos)
git clone git@github.com:acme/node-api-template.git billing-api
cd billing-api
rm -rf .git && git init
npm ci
 
# 2. O un scaffolding manual mínimo
npm init -y
npm pkg set type=module
npm pkg set scripts.dev="tsx watch src/server.ts"
npm pkg set scripts.build="tsc -p tsconfig.build.json"
npm pkg set scripts.start="node dist/server.js"
npm pkg set scripts.test="node --import tsx --test"
npm install express@5
npm install -D typescript@5.6 tsx @types/node @types/express
npx tsc --init --module NodeNext --moduleResolution NodeNext --strict
mkdir -p src test

// src/server.ts
import express from "express";
 
export function createApp() {
  const app = express();
  app.use(express.json());
  app.get("/health", (_req, res) => res.json({ ok: true }));
  return app;
}
 
if (import.meta.url === `file://${process.argv[1]}`) {
  createApp().listen(3000);
}

Lo que esto demuestra:

• Los repositorios de plantillas codifican las decisiones de la organización (ESLint, Docker, CI) una sola vez.
• npm pkg set scripts sin editar JSON a mano.
• La exportación createApp() permite pruebas de integración con Supertest desde el primer día.

Análisis profundo

Cómo funciona

• npm init crea package.json; los frameworks añaden enrutamiento, DI y convenciones.
• NestJS CLI genera módulos, controladores y el grafo de construcción nest-cli.json.
• Fastify CLI y Express tienen scaffolds más ligeros: tú aportas más estructura.
• Los repositorios de plantillas deben ejecutar npm ci && npm test en CI para demostrar que funcionan.

CLIs de frameworks

Notas de TypeScript

npm install -D typescript@5.6 tsx
# tsconfig: "module": "NodeNext", "strict": true

• Scaffolding con la misma configuración de module que usas en las compilaciones de producción.
• Añade test/ y una prueba de ejemplo en la plantilla para que CI nunca esté vacío.

Errores comunes

• Dependencias de plantilla obsoletas - Los nuevos servicios heredan versiones antiguas de Express 4. Solución: Renovate en el repositorio de la plantilla; versionar los lanzamientos de la plantilla.
• Los valores predeterminados de CLI usan un gestor de paquetes incorrecto - Nest pregunta por yarn a menos que pases --package-manager npm. Solución: scriptear las banderas en la documentación.
• Falta la exportación createApp - Es difícil probar la integración de servidores que solo llaman a listen() al importar. Solución: exportar la fábrica; iniciar el servidor en el guard if (main).
• Copiar .env de proyectos antiguos - Los secretos se filtran en el historial de git. Solución: solo .env.example en las plantillas.
• Estructura de Nest sobregenerada - La CLI predeterminada crea más carpetas de las que necesita una API pequeña. Solución: podar módulos o usar una plantilla interna más ligera.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de configuración de proyectos - diseño de carpetas estándar
• Turborepo para Node - siguiente paso de scaffolding de monorepo
• Nx para backends de Node - configuración basada en generadores

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