Conceptos básicos de incorporación

10 ejemplos para la configuración del primer día: Node LTS, gestor de paquetes, Docker, Postgres/Redis local, para que un nuevo compañero de equipo ejecute la API antes del almuerzo.

Prerrequisitos

Clona el repositorio del equipo y confirma el contrato de la pila antes de instalar las dependencias.

git clone git@github.com:your-org/your-api.git
cd your-api
node -v   # se espera v24.18.0
cat package.json | grep '"engines"'

Pila objetivo para esta sección:

{
  "engines": { "node": "24.18.0", "npm": ">=10.0.0" },
  "packageManager": "npm@10.8.0"
}

Herramientas: Node.js 24.18.0 (LTS activa), TypeScript 5.6+, Fastify 5 o Nest 11 por ADR de servicio.

Ejemplos básicos

1. Node 24 LTS con fnm o nvm

# ejemplo de fnm
fnm install 24.18.0
fnm use 24.18.0
node -v   # v24.18.0
npm -v    # 10.x

# .nvmrc
24.18.0

• Fija la versión de Node antes de npm ci - una versión incorrecta de Node causa errores ABI de módulos nativos
• engines en package.json debe coincidir con .nvmrc

Relacionado: Instalación y gestión de versiones

2. Instalar dependencias con npm ci

npm ci

• Usa npm ci, no npm install, en un clon nuevo para que coincida exactamente con CI
• Si el equipo usa pnpm, ejecuta corepack enable && pnpm install --frozen-lockfile en su lugar
• Una política de lockfile por repositorio - consulta Conceptos básicos de gestores de paquetes

3. Variables de entorno

cp .env.example .env

# .env.example (comprometido)
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://app:app@localhost:5432/app_dev
REDIS_URL=redis://localhost:6379
LOG_LEVEL=debug

• Nunca subas .env con secretos reales
• Los secretos de producción provienen de la inyección de la plataforma, no de archivos

Relacionado: Conceptos básicos de configuración

4. Docker Compose para Postgres y Redis

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports: ["5432:5432"]
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

docker compose up -d
npm run db:migrate

• Los almacenes de datos locales coinciden con la topología de producción (SQL + Redis) incluso si la producción es RDS/ElastiCache gestionado
• Documenta que docker compose down -v borra los datos - advierte a los nuevos empleados

5. Iniciar la API y verificar la salud

npm run dev
curl -sf http://localhost:3000/health | jq .
curl -sf http://localhost:3000/ready | jq .

• Ruta verde: ambos devuelven 200 antes de asignar trabajo de características
• Si ready falla, verifica DATABASE_URL y los logs del contenedor de Postgres

Relacionado: Conceptos básicos de CLI para Node

6. Ejecutar la suite de pruebas

npm test
npm run typecheck
npm run lint

• Los mismos tres comandos que ejecuta CI - apréndelos el primer día
• Corrige los fallos localmente antes de abrir la primera PR

7. Lista de verificación de CONTRIBUTING.md

Cada repositorio debe documentar:

## Inicio rápido
1. fnm use / nvm use
2. npm ci
3. cp .env.example .env
4. docker compose up -d && npm run db:migrate
5. npm run dev
6. npm test

• El compañero guía al nuevo empleado a CONTRIBUTING.md en los primeros 30 minutos
• La confusión del primer día se convierte en una PR de documentación para el quinto día

Ejemplos intermedios

8. Arranque de monorepo

cd your-monorepo
npm ci                    # la raíz instala los workspaces
npm run build --workspaces --if-present
cd services/orders-api
npm run dev

• El package.json raíz define workspaces
• El nuevo empleado trabaja en un servicio primero, no en todo el monorepo el primer día

Relacionado: Workspaces y Monorepos

9. Configuración de IDE y depurador

// .vscode/launch.json (extracto)
{
  "type": "node",
  "request": "launch",
  "name": "Debug API",
  "runtimeArgs": ["--import", "tsx"],
  "args": ["src/server.ts"]
}

• Sube la configuración de lanzamiento compartida de VS Code/Cursor
• La depuración con puntos de interrupción supera a console.log para aprender el flujo asíncrono

10. Asignación de compañero el primer día

## Nuevo empleado: Alex - inicio 2026-07-09
Compañero: Jordan (backend, 2 años)
Día 1: Configuración de la máquina + salud en verde + recorrido por el código base Nivel 1
Día 2: Pequeña PR de documentación (corregir ruta de README)
Día 3-5: Primera PR de característica con emparejamiento

• Compañero asignado - no "pregunta en Slack"
• Consulta Mejores prácticas de equipo e incorporación

Preguntas frecuentes

Relacionado

• Ruta de Frontend → Node - curva de aprendizaje de la primera semana
• Matriz de habilidades - expectativas de nivelación
• Mejores prácticas de equipo e incorporación - resumen de 25 elementos

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.