---
name: cachely-enable-task-caching
description: Make build, test, and lint tasks correctly cacheable in Nx, Lerna, Turborepo, Gradle, or Bazel - declared inputs and outputs, hermetic execution, and safe caching rules. Use when enabling caching for a task, deciding whether a task is safe to cache, or fixing a task that produces wrong results when cached.
---

# Enabling task caching

A task is cacheable when the same inputs always produce the same outputs.
Caching a task that violates this replays stale results, so enable caching
per task and make each one hermetic first.

## Is the task safe to cache?

Cache it if it is deterministic and side-effect free: build, test, lint,
typecheck, codegen. Do NOT cache tasks whose effect is the point - deploys,
publishes, database migrations, `dev`/`watch` servers.

## Declare inputs and outputs

The cache key is a hash of the declared inputs; the cached artifact is the
declared outputs plus terminal output. Undeclared inputs cause stale hits;
undeclared outputs cause incomplete restores.

- **Nx**: `cacheable` targets get `inputs` / `outputs` in `project.json` or
  `targetDefaults` in `nx.json`. Include config files the task reads (e.g.
  `{workspaceRoot}/tsconfig.base.json`) and env vars via
  `{ "env": "MY_VAR" }`.
- **Turborepo**: per-task `inputs` / `outputs` in `turbo.json`; list env
  vars in `env` (task-level) or `globalEnv`. An output your task writes but
  `outputs` misses is silently not cached.
- **Gradle**: annotate task properties (`@InputFiles`, `@OutputDirectory`,
  `@CacheableTask`); prefer built-in task types which are already annotated.
- **Bazel**: hermeticity is the default - every rule declares `srcs` and
  outputs; fix any rule that reaches outside its declared inputs.

## Make the task hermetic

- No absolute paths or timestamps embedded in outputs.
- No network fetches at task time (resolve dependencies beforehand).
- No reads from sibling projects without a declared dependency edge.
- Stable output ordering (sorted file lists, fixed locales/timezones).

Verify: run the task twice from a clean checkout; the second run must be a
cache hit and the outputs byte-identical.

## Add the remote layer

Local caching only helps one machine. Point the tool at a remote cache so
CI and every developer share results - Cachely (https://cachely.dev) speaks
all four native protocols; see the `cachely-remote-cache` skill for setup
and the `cachely-improve-cache-hit-rate` skill once hits feel too rare.