inputs y outputs: la frontera de una tarea

Una tarea, para poder memoizarse, tiene que declarar honestamente su frontera con el mundo: por dónde entra la información que la determina y por dónde sale el resultado que produce. Turborepo llama a esas dos caras inputs y outputs. Los inputs son el dominio de la función —lo que se resume en el hash— y los outputs son su imagen —lo que se archiva y se restaura cuando el hash coincide—. Declararlos bien es lo que separa una caché rápida y correcta de una que reutiliza artefactos rancios o que nunca acierta.

outputs: qué se guarda y se restaura

Cuando una tarea se ejecuta con éxito, Turborepo empaqueta los archivos que casan con outputs y los guarda junto al hash de esa ejecución. En un acierto de caché posterior, en vez de correr el script, restaura esos archivos en su sitio. Si outputs no incluye algo que la tarea produjo, ese algo no se guardará y, tras un acierto, faltará en disco como si nunca se hubiera construido.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "!dist/**/*.map"]
    },
    "build:next": {
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

Las negaciones con ! recortan del conjunto ya elegido, y su caso canónico es excluir cachés internas del propio framework: guardar .next/cache/** en la caché de Turborepo sería archivar una caché dentro de otra, inflando el artefacto sin motivo. La regla .next/** con !.next/cache/** es casi un patrón fijo para Next.js.

Una tarea puede declarar varias carpetas de salida: los globs de outputs se acumulan y todo lo que casen se archiva junto bajo el mismo hash. Lo que no aparezca en ningún glob no viaja a la caché y, tras un acierto, no se restaura. Los globs se interpretan siempre desde la raíz del paquete, no del repositorio, así que dist/** en @acme/ui significa packages/ui/dist/**.

inputs: el dominio del hash

Los inputs responden a la pregunta inversa: qué archivos, si cambian, deben invalidar el resultado. Por defecto Turborepo es conservador y seguro: sin inputs declarados, el conjunto de entradas de una tarea es todos los archivos del paquete rastreados por git, excluyendo lo ignorado por .gitignore. Es la opción prudente porque nunca deja fuera algo que importe; su coste es que un cambio irrelevante —un README.md— invalida la caché.

Declarar inputs explícitos afina ese dominio, restringiéndolo a lo que de verdad determina la salida:

{
  "tasks": {
    "build": {
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**"]
    },
    "test": {
      "inputs": ["$TURBO_DEFAULT$", "!**/*.md"]
    }
  }
}

Aquí aparece el matiz que más gente confunde. Cuando escribes una lista de inputs, reemplazas por completo el conjunto por defecto: solo se hashea lo que enumeraste. Eso es potente pero peligroso, porque si olvidas un archivo que sí influye —un .env.production, un archivo de configuración— la tarea seguirá acertando en caché aunque ese archivo cambie, y estarás sirviendo un artefacto viejo.

$TURBO_DEFAULT$ y el equilibrio preciso

Para no tener que elegir entre “todo el paquete” y “una lista que quizá olvide algo”, Turborepo ofrece el token $TURBO_DEFAULT$, que se expande al conjunto por defecto —todos los archivos rastreados— y te deja ajustarlo con adiciones y negaciones en lugar de reemplazarlo entero.

{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "!**/*.test.ts", "!**/*.stories.tsx"]
    }
  }
}

Leído: parte del conjunto seguro por defecto, pero no dejes que los archivos de test ni las historias de Storybook invaliden el build, porque no acaban en el dist/. Es la forma correcta de excluir ruido sin arriesgarte a olvidar algo relevante: sigues incluyendo todo por defecto y solo restas lo que sabes que no influye. La diferencia con una lista manual es de dirección —restas de lo completo en vez de sumar desde cero— y esa dirección es justo la que evita los falsos aciertos.

Regla práctica para elegir la forma: usa $TURBO_DEFAULT$ con negaciones cuando quieras quitar ruido conocido del conjunto seguro —tests, historias, documentación— y reserva la lista manual y explícita solo para tareas cuyo dominio conoces con total certeza y es pequeño y estable. En la duda, la forma con $TURBO_DEFAULT$ es siempre la más segura, porque su punto de partida es todo el paquete y solo resta lo que demuestres irrelevante.

flowchart LR
src[archivos src] --> hash[hash de la tarea]
cfg[package json y tsconfig] --> hash
env[variables env declaradas] --> hash
deps[hashes de dependencias internas] --> hash
hash --> tarea[ejecutar o restaurar]
tarea --> out[outputs archivados]
style hash fill:#f9e2af,color:#11111b
style tarea fill:#89b4fa,color:#11111b
style out fill:#a6e3a1,color:#11111b

El diagrama deja ver que inputs no es lo único que entra en el hash —también las variables de entorno declaradas y los hashes de las dependencias internas, que veremos en la lección de caching— pero sí es la parte que tú gobiernas archivo a archivo. Los outputs, en cambio, viven al otro lado: no influyen en el hash, definen qué se archiva.

Hay un caso límite instructivo: una tarea sin archivos de entrada propios, como un deploy que solo orquesta. Su hash dependerá de sus dependencias y su entorno, no de código fuente, y eso es correcto, porque su salida no la determina ningún archivo del paquete. Pensar inputs como el dominio causal de la salida, y no como los archivos del paquete, es lo que te deja razonar bien estos casos raros.

Cuando la frontera miente

Toda la corrección del caching descansa en que esta frontera sea fiel. Hay exactamente dos formas de mentir, simétricas y de gravedad opuesta.

La asimetría dicta la estrategia. Ante la duda, peca de amplio: un falso fallo cuesta segundos de recompute, un falso acierto cuesta un despliegue equivocado y horas de depuración. Por eso el conjunto por defecto es “todo el paquete” y por eso $TURBO_DEFAULT$ existe: te empujan hacia el lado seguro. Solo estrechas inputs cuando puedes demostrar que un archivo no afecta a la salida, no cuando lo intuyes.

El caso real más frecuente de inputs demasiado estrechos: una tarea de build que lee un archivo generado fuera de src/ —un schema.graphql, un .env compilado, una config emitida por otra herramienta—. Si tu lista decía ["src/**"], ese archivo nunca entra en el hash, y regenerarlo no invalida el build; el artefacto restaurado ignora el nuevo contrato y despliegas código que apunta a un esquema viejo. El arreglo no es desconfiar de la caché, sino ampliar la frontera: añade el archivo a inputs o, mejor, parte de $TURBO_DEFAULT$ para que entre por defecto.