Turborepo para Node

Turborepo orquesta las tareas del espacio de trabajo con caché remota para que los paquetes sin cambios omitan las reconstrucciones en CI y localmente.

Receta

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

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

npx turbo run build test typecheck

Cuándo usarlo:

• Monorepo con más de 3 paquetes y build/test repetidos en CI.
• Las bibliotecas compartidas deben compilarse antes de que las aplicaciones realicen la verificación de tipos.
• Quieres aciertos de caché entre desarrolladores y ejecutores de CI.

Ejemplo de trabajo

platform/
  turbo.json
  package.json          # workspaces
  apps/
    api/package.json
  packages/
    shared/package.json

// package.json (root)
{
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "dev": "turbo run dev --parallel"
  },
  "devDependencies": {
    "turbo": "^2.3.0",
    "typescript": "^5.6.0"
  }
}

// packages/shared/package.json
{
  "name": "@acme/shared",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "test": "node --import tsx --test"
  }
}

// apps/api/package.json
{
  "name": "@acme/api",
  "dependencies": { "@acme/shared": "workspace:*", "fastify": "^5.0.0" },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "dev": "tsx watch src/server.ts",
    "test": "node --import tsx --test"
  }
}

npm install
npx turbo run build --filter=@acme/api...

Lo que esto demuestra:

• ^build ejecuta las compilaciones de paquetes de dependencia antes que los dependientes.
• --filter=@acme/api... incluye la API y sus dependencias del espacio de trabajo.
• outputs le dice a Turbo qué almacenar en caché entre ejecuciones.

Análisis profundo

Cómo funciona

• Turbo hash los inputs de la tarea (código fuente, variables de entorno, dependencias) y restaura outputs del caché en caso de acierto.
• dependsOn construye un DAG; test espera los artefactos de build.
• La caché remota (Vercel o autoalojada) comparte los aciertos entre las máquinas de CI.
• Las tareas dev suelen ser persistent: true y no se almacenan en caché.

Configuración de tareas

Notas de TypeScript

{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "typecheck": { "dependsOn": ["^build"] }
  }
}

• Separa typecheck de build si quieres trabajos de CI más rápidos que omitan la emisión al verificar solo los tipos.
• Asegúrate de que cada tsconfig del paquete emita a dist/ de forma consistente para las rutas de caché.

Errores comunes

• outputs faltantes - Turbo no almacena nada útil en caché; cada compilación se vuelve a ejecutar por completo. Solución: declara dist/** por tarea de compilación.
• Sintaxis de filtro incorrecta - @acme/api solo omite las compilaciones de dependencia. Solución: usa @acme/api... (tres puntos) para la cadena de dependientes.
• Pruebas de caché con efectos secundarios - Las pruebas que acceden a una base de datos real obtienen un falso positivo del caché. Solución: excluye las pruebas de integración de las tareas cacheadas o usa inputs únicos.
• Secretos de entorno en el hash - Las listas env invalidan la caché cuando cambian los tokens. Solución: solo lista las variables de entorno que afectan la salida de la compilación.
• Tarea dev cacheadas por error - El modo de observación no debe almacenar en caché. Solución: "persistent": true y sin outputs en dev.

Alternativas

Preguntas frecuentes

npx turbo run dev --filter=@acme/api

Relacionado

• Workspaces y Monorepos - enlace de workspaces
• Monorepo de múltiples servicios - límites desplegables
• Nx para backends de Node - orquestación alternativa

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.