Conceptos básicos de configuración de proyectos

9 ejemplos para empezar con la configuración de proyectos: 7 básicos y 2 intermedios.

Prerrequisitos

• Node.js 24.18.0 y npm 10+.
• TypeScript 5.6+: npm init -y && npm install -D typescript@5.6 tsx @types/node.
• Git inicializado: git init && git add . && git commit -m "init".

Ejemplos básicos

1. Diseño estándar de servicio API

Separa el código fuente, las pruebas y la configuración en la raíz del repositorio para mayor claridad.

billing-api/
  src/
    server.ts
    routes/
    services/
  test/
    health.test.ts
  package.json
  tsconfig.json
  Dockerfile
  .gitignore

• src/ contiene el código TypeScript de tiempo de ejecución; test/ refleja las carpetas de dominio.
• Los archivos de configuración se encuentran en la raíz para que las herramientas los descubran sin banderas adicionales.
• Un elemento desplegable por repositorio a menos que adoptes un diseño de monorepo explícito.

Relacionado: Scaffolding APIs - arranca desde plantillas

2. Scripts de package.json para desarrollo y producción

Conecta los comandos diarios que ejecutan cada colaborador y cada trabajo de CI.

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/server.js",
    "test": "node --import tsx --test",
    "typecheck": "tsc --noEmit"
  }
}

• dev para iteración local; start ejecuta la salida compilada en producción.
• typecheck falla rápidamente sin emitir archivos.
• Los scripts son el contrato: documéntalos en el README.

3. Configuración de TypeScript dividida

Usa configuraciones separadas para la salida de la compilación y para la verificación de tipos del editor/CI.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "rootDir": ".",
    "types": ["node"]
  },
  "include": ["src", "test"]
}

// tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "noEmit": false, "outDir": "dist", "rootDir": "src" },
  "include": ["src"]
}

• NodeNext coincide con la resolución ESM de Node 24.
• La configuración de compilación excluye las pruebas de dist/ de producción.

4. Archivos de entorno y Gitignore

Mantén los secretos fuera de git; documenta las variables requeridas.

# .gitignore
node_modules/
dist/
.env
.env.local
coverage/

# .env.example (committed)
PORT=3000
DATABASE_URL=postgres://localhost:5432/billing
LOG_LEVEL=info

• Confirma .env.example, nunca .env.
• Carga y valida el entorno al inicio (esquema Zod en un paso posterior de endurecimiento del servicio).

5. Dockerfile mínimo

Compilación de varias etapas: instala, compila, ejecuta una imagen de tiempo de ejecución ligera.

FROM node:24.18.0-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:24.18.0-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/server.js"]

• Fija el parche de Node en FROM para que coincida con engines.
• Copia el archivo de bloqueo antes del código fuente para el almacenamiento en caché de capas de Docker.

6. Punto de entrada de verificación de estado

Cada servicio expone una ruta de actividad desde el primer día.

// src/server.ts
import express from "express";
 
const app = express();
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});
 
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => console.log(`listening on ${port}`));

• /health es amigable para el balanceador de carga y el orquestador.
• Mantenlo libre de llamadas a la base de datos para una actividad básica (la preparación puede ser separada).

7. Bloque de incorporación en el README

Los nuevos empleados ejecutan tres comandos y obtienen una prueba exitosa.

## Inicio rápido
npm ci
cp .env.example .env
npm run dev
 
## Verificaciones
npm run typecheck
npm test

• El README es parte de la configuración del proyecto, no una ocurrencia tardía.
• Haz que los comandos coincidan exactamente con los scripts de package.json.

Ejemplos intermedios

8. Carpetas de prueba colocalizadas vs. separadas

Elige una convención por repositorio y aplícala.

# Opción A: test/ de nivel superior (mostrado arriba)
test/routes/health.test.ts

# Opción B: colocalizado
src/routes/health.test.ts

• test/ de nivel superior mantiene dist/ limpio sin reglas de exclusión adicionales.
• Las pruebas colocalizadas se encuentran junto a los módulos, lo cual es bueno para dominios con muchas unidades.
• Nunca mezcles ambos patrones en un solo servicio.

Relacionado: Conceptos básicos de pruebas - pirámide para APIs

9. Monorepo vs. repositorio de un solo servicio

Comienza con un solo servicio; divídelo cuando los límites estén claros.

• Los monorepos prematuros gravan cada PR con gastos generales de coordinación.
• Extrae el código compartido cuando el tercer servicio copie el mismo módulo.

Relacionado: Monorepo multiservicio - reglas de límite

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.