Caching local: el hash y el replay

Todo lo anterior —el grafo, dependsOn, inputs, outputs— existe para habilitar un único acto: no volver a ejecutar una tarea cuyas entradas no cambiaron. El mecanismo es una tabla de memoización indexada por un hash de contenido. Turborepo calcula, para cada nodo del grafo, una huella que resume todo lo que lo determina; si esa huella ya está en la caché local, restaura los archivos que se guardaron y reproduce en pantalla los logs de aquella vez, sin correr un solo comando. A un acierto total el propio Turborepo lo anuncia con dos palabras: FULL TURBO.

El hash: la huella de una tarea

El hash de una tarea es una función criptográfica sobre todo lo que puede alterar su salida. Turborepo lo compone en dos capas. Hay un hash global, compartido por todas las tareas, que incluye el lockfile de la raíz, los globalDependencies, las globalEnv y la propia versión y config de Turborepo. Y hay un hash por tarea, que añade a lo global los ingredientes locales de ese nodo.

La inclusión de los hashes de las dependencias es lo que propaga la invalidación por el grafo: tocar un archivo de utils cambia el hash de utils#build, que forma parte del hash de ui#build, que forma parte del de web#build. Un solo cambio en una hoja invalida exactamente su cono de dependientes, ni un nodo más. Esa cascada es el grafo de tareas funcionando como una estructura de propagación, no solo de orden.

Conviene subrayar qué no entra en el hash, porque las sorpresas suelen venir de ahí: no entra la hora, ni el orden en que lanzaste las tareas, ni las banderas que no afectan la salida, ni los archivos ignorados por .gitignore. El hash aspira a capturar exactamente los factores causales de la salida y nada más; cada factor de más provoca fallos de caché espurios, y cada factor de menos, aciertos incorrectos.

Acierto de caché: restaurar y reproducir

Con el hash calculado, Turborepo consulta la caché local. Por defecto vive dentro del repositorio, en node_modules/.cache/turbo, y es configurable con el campo cacheDir o la bandera --cache-dir. Cada entrada guarda dos cosas: los artefactos que casaban con outputs y la salida de terminal que la tarea produjo.

En un fallo de caché —hash nuevo— Turborepo ejecuta el script, captura su salida y, si termina bien, archiva outputs y logs bajo ese hash. En un acierto —hash conocido— no ejecuta nada: copia los artefactos de vuelta a su sitio y reproduce los logs guardados en el terminal, de modo que la experiencia es idéntica a haber corrido la tarea, solo que en milisegundos. Cuando todas las tareas de una invocación son aciertos, aparece el célebre cartel.

turbo run build
# ...
#  Tasks:    12 successful, 12 total
# Cached:    12 cached, 12 total
#   Time:    240ms >>> FULL TURBO

Los logs de cada tarea se guardan además en un archivo por paquete, .turbo/turbo-<tarea>.log, que es literalmente lo que se reproduce en un acierto. Cuánta salida se imprime lo gobierna outputLogs: full reproduce todo, hash-only solo la línea del hash, new-only calla en los aciertos, errors-only solo habla si algo falla, y none enmudece del todo.

Inspeccionar, forzar y afinar

La herramienta para entender por qué una tarea acierta o falla es el --dry-run, que imprime el hash de cada tarea y los ingredientes que lo forman sin ejecutar nada. Comparar dos --dry-run es la forma de descubrir qué cambió para que un hash se moviera.

turbo run build --dry-run             # tabla legible con el hash de cada tarea
turbo run build --dry=json            # el mismo plan en json, para diffs
turbo run build --force               # ignora la cache y reejecuta todo
turbo run build --output-logs=errors-only

--force es la vía para saltarse la caché cuando sospechas que quedó envenenada o quieres medir el tiempo real de un build en frío. Su existencia es también un recordatorio incómodo: si alguna vez necesitas forzar porque la caché sirve algo incorrecto, no tienes un problema de caché sino de hash —algo influía en la salida sin estar declarado en inputs, env o globalDependencies—.

Los modos de outputLogs afinan el ruido en aciertos masivos. En un monorepo grande, ver los logs completos de doscientas tareas cacheadas es inútil; new-only calla en los aciertos y solo habla cuando algo se ejecutó de verdad, que suele ser lo único que quieres leer.

turbo run build --output-logs=new-only     # silencio en los aciertos
turbo run build --output-logs=errors-only  # habla solo si algo falla
turbo run build --summarize                 # escribe un resumen json de la corrida

Un flujo de diagnóstico que vale la pena adoptar: cuando una tarea falla en caché y no entiendes por qué, guarda el --dry=json antes y después del cambio y compara los dos objetos. El hash y el desglose de sus ingredientes te dicen exactamente qué entrada se movió —un archivo, una variable, el hash de una dependencia— sin que tengas que adivinar. Turborepo no esconde el porqué de una invalidación: solo hay que pedírselo.

flowchart TD
start[turbo run build] --> calc[calcular hash de la tarea]
calc --> q{hash en cache}
q -->|si| restore[restaurar outputs y reproducir logs]
q -->|no| exec[ejecutar el script]
exec --> save[archivar outputs y logs bajo el hash]
restore --> done[FULL TURBO]
save --> done2[tarea completada]
style q fill:#f9e2af,color:#11111b
style restore fill:#a6e3a1,color:#11111b
style exec fill:#89b4fa,color:#11111b

Correctitud: el hash debe verlo todo

Un caché solo es tan correcto como completo sea su hash. Si un factor influye en la salida y no entra en la huella, Turborepo servirá artefactos que no corresponden a las entradas reales. El caso más traicionero son las variables de entorno: un build que lee API_URL produce artefactos distintos según su valor, y si no la declaras en env, el hash no la ve y la caché mezcla builds de entornos distintos.

Por eso Turborepo 2.x activa por defecto el modo de entorno estricto: dentro de una tarea, solo están disponibles las variables que declaraste en env, globalEnv o passThroughEnv; el resto se ocultan. Es una restricción deliberadamente incómoda que convierte un bug silencioso —una variable no declarada que envenena la caché— en un fallo ruidoso y temprano —la variable simplemente no existe hasta que la declaras—.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["API_URL", "SENTRY_DSN"],
      "passThroughEnv": ["CI"]
    }
  }
}

El modo estricto tiene un coste de fricción real: la primera vez que lo activas sobre un proyecto viejo, tareas que “funcionaban” empiezan a quejarse de variables ausentes. Esa fricción es el sistema haciendo su trabajo, obligándote a declarar la superficie de entorno que antes consumías a ciegas. Cada variable que añades a env es una pieza del contrato de pureza que faltaba, y el proyecto queda mejor documentado y su caché, de fiar.

De la caché local a la compartida

La caché local vive en tu máquina, pero el hash es una clave universal: si es un contrato honesto de las entradas, dos máquinas que calculan el mismo hash deben poder intercambiar el mismo artefacto. Esa es la premisa de la caché remota, donde el resultado de una tarea que construyó un compañero —o el propio CI— se descarga en vez de recomputarse. Turborepo la ofrece gestionada o autoalojada, y no cambia nada de lo aprendido: sigue siendo la misma tabla de memoización, solo que su almacén se comparte por la red.

Por eso la disciplina del hash importa aún más al activarla. Un hash local puede tolerar impurezas que se cancelan porque siempre corres en la misma máquina; un hash compartido no perdona ninguna. Si algo específico de tu entorno —una ruta absoluta, una variable no declarada, una versión de herramienta que no entra en globalDependencies— se cuela en la salida sin entrar en el hash, envenenarás la caché de todo el equipo, no solo la tuya. La caché remota convierte cada descuido de frontera de un problema personal en un problema colectivo, y por eso es el mejor examen de si tus tareas son de verdad puras.