turbo.json: tasks, dependsOn y topología

Si el grafo de tareas es la idea, turbo.json es donde la escribes. No enumeras nodos uno a uno —serían cientos— sino reglas que Turborepo expande sobre el grafo de paquetes para generar el grafo de tareas concreto. La pieza central es dependsOn, y dentro de ella un solo carácter, el circunflejo ^, carga con casi toda la semántica: distingue entre necesitar la misma tarea en las dependencias, la misma tarea en el propio paquete, o un nodo específico. Dominar esa gramática es dominar Turborepo.

Anatomía de tasks

Un turbo.json mínimo declara un $schema para autocompletado y un objeto tasks. Cada clave de tasks es el nombre de una tarea —el mismo que en los scripts del package.json— y su valor describe cómo se comporta esa tarea en todos los paquetes que la definan.

{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Los campos por tarea más frecuentes: dependsOn fija las precedencias; outputs declara qué artefactos produce —lo verás a fondo en la próxima lección—; cache desactiva la memoización para tareas que no la admiten; persistent marca procesos de larga duración —un servidor de dev— que no terminan y de los que nadie puede depender; env lista las variables de entorno que influyen en el resultado; y outputLogs controla cuánta salida se imprime en un acierto de caché.

El operador circunflejo: topología en una línea

Aquí está el corazón. dependsOn toma una lista de referencias a tareas, y el prefijo cambia radicalmente su significado.

La regla "build": { "dependsOn": ["^build"] } es, con diferencia, la más importante de todo Turborepo. Leída en voz alta: para construir cualquier paquete, construye primero aquello de lo que depende. Con esa única línea, Turborepo recorre el grafo workspace: que le da pnpm y genera todas las aristas topológicas del grafo de tareas, sin que tú enumeres ninguna.

flowchart TD
utb[utils build] --> uib[ui build]
utb --> apib[api build]
uib --> webb[web build]
apib --> webb
webb --> webt[web test]
style utb fill:#f9e2af,color:#11111b
style uib fill:#a6e3a1,color:#11111b
style apib fill:#a6e3a1,color:#11111b
style webb fill:#89b4fa,color:#11111b
style webt fill:#cba6f7,color:#11111b

En ese grafo, web#build no arranca hasta que terminan ui#build y api#build —sus dependencias vía ^build—, y web#test espera a web#build por la regla test de mismo paquete. Turborepo dibujó todo eso a partir de dos reglas y del grafo de paquetes. Añade mañana un paquete nuevo entre medias y las aristas se recalculan solas: nunca codificas secuencias a mano.

Mismo paquete, nodos concretos y persistentes

La distinción entre ^build y build es sutil y decide correctitud. dependsOn: ["build"] en la tarea test no fuerza a construir las dependencias, solo el propio paquete; si tus tests importan el dist/ de un paquete vecino, necesitarás ["build", "^build"] para exigir ambos. Combinar prefijos en la misma lista es idiomático y frecuente.

{
  "tasks": {
    "test": { "dependsOn": ["build", "^build"] },
    "deploy": { "dependsOn": ["build", "test", "lint"] },
    "db:migrate": { "cache": false },
    "typecheck": { "dependsOn": ["^typecheck"] }
  }
}

Las tareas persistentes merecen cuidado: un servidor de desarrollo no termina, así que marcarlo persistent: true le dice a Turborepo que no espere su fin y que prohíba a otras tareas depender de él —depender de algo que nunca acaba bloquearía el grafo—. Para acompañar un persistente con tareas auxiliares está el campo with, que las corre en paralelo sin crear una arista de precedencia.

Configuración global y config por paquete

No todo cabe dentro de una tarea. Hay archivos y variables que afectan a todas las tareas por igual —un tsconfig.json de raíz, un .env, la versión de Node— y para eso está el ámbito global, que entra en el hash de absolutamente todos los nodos.

{
  "$schema": "https://turborepo.com/schema.json",
  "globalDependencies": ["tsconfig.base.json", ".env"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }
  }
}

Cambiar cualquier archivo de globalDependencies invalida la caché de todo el monorepo, porque se asume que puede afectar a cualquier tarea; por eso la lista debe ser corta y verdadera. Para reglas específicas de un paquete sin ensuciar la raíz, Turborepo admite un turbo.json propio dentro del paquete que extiende al de raíz con "extends": ["//"] y sobrescribe solo las tareas que necesite. El símbolo // designa la raíz del workspace, y también sirve para declarar tareas de raíz con la sintaxis //#tarea.

Un turbo.json de paquete solo menciona lo que cambia respecto a la raíz:

// packages/docs/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["build/**"],
      "env": ["DOCS_BASE_URL"]
    }
  }
}

Con extends: ["//"], la tarea build de docs hereda el dependsOn: ["^build"] de la raíz pero sobrescribe sus outputs y añade una variable propia. Es la vía para que un paquete con necesidades peculiares no obligue a ensuciar la configuración común, y para mantener la raíz como el contrato mínimo que comparten todos.

Las tareas de raíz —las que no pertenecen a ningún paquete, como un formateo global o un chequeo de licencias— se declaran con el prefijo //# y corren una sola vez sobre el repositorio entero:

{
  "tasks": {
    "//#format": {
      "outputs": [],
      "cache": false
    }
  }
}