Skip to content
Monorepo Skills

Check 3 — Task caching

Question: will a cache hit ever replay a wrong result, and are tasks re-running when they should hit? Output: findings/caching.json. If no orchestrator is detected, only caching/uncached-root-script applies; set status ok with reason no task orchestrator.

Facts the rules rely on

Section titled “Facts the rules rely on”
  • Turborepo: a task with no outputs caches only logs — on a hit, dist/ is NOT restored, so downstream tasks see stale or missing files. A package’s hash covers its own files, its package.json, turbo.json and the lockfile; changes in workspace dependencies reach a task’s hash only through dependsOn entries with ^ (e.g. ^build). Env vars affect the hash only when listed in env, globalEnv (or passThroughEnv for runtime-only); framework prefixes such as NEXT_PUBLIC_, VITE_ are auto-included. Turbo 2 strict env mode can also restrict which env vars are visible to tasks, so undeclared env is both a cache-key and runtime-visibility risk.
  • Nx: when outputs is omitted, Nx caches {workspaceRoot}/dist/{projectRoot}, {projectRoot}/dist, {projectRoot}/build, {projectRoot}/public. Env vars affect the hash only through an { "env": "NAME" } entry in inputs. Without a production named input that excludes tests, editing a spec file invalidates the build cache.

Rules

Section titled “Rules”
id severity detect
caching/missing-outputs high Turbo: a cacheable task named build/compile/bundle/*:build (or whose package script runs tsc, vite build, tsup, rollup, webpack, next build, esbuild) has no outputs. Package-level turbo.json overrides count. Nx: cacheable build-like target without outputs whose real out dir (outDir in the build tsconfig, outDir/--out-dir flags, build.outDir in vite config) is not one of Nx’s defaults — one finding per affected project, with package. Turbo findings are per task: location.file: "turbo.json", no package.
caching/build-inputs-include-tests low Turbo: build-like task has no inputs, or inputs that don’t exclude test globs (!**/*.test.*, !**/*.spec.*, !**/__tests__/**). Nx: no production named input, or build inputs don’t reference it, or production doesn’t negate test globs. Low severity because $TURBO_DEFAULT$ already covers all git-tracked files; the finding is about avoiding rebuilds when tests change, not correctness. Follow dependsOn chains: tests hashed by a dependency task (e.g. a transit task, or ^build of a package whose build inputs include tests) also invalidate the build. Measure impact (step 3) and put it in evidence.
caching/undeclared-env medium for each scan.env entry that can affect a cacheable task output. Flag build tasks only when the build inlines env (Next/Vite framework bundlers, webpack/Rspack/Rsbuild define, esbuild/tsup define, Rollup/plugin-replace, or similar bundlers), not runtime-only reads in a plain tsc service. Always flag cacheable test tasks when tests execute code that reads the env var (scan.env.isTest, or a test file in the package imports the module with the env read), because a cached pass can be replayed under a different value. Turbo: name not matched by the task’s env or globalEnv (* wildcards; ! negation) and not framework-prefixed. passThroughEnv / globalPassThroughEnv do not count: they make the var available without adding it to the hash, so a cached result can still be replayed under a different value. Nx: no { "env": NAME } in the target’s inputs (resolve named inputs). Ignore CI, PATH, HOME, TZ, PWD. Ignore NODE_ENV only when the scan confirms it cannot affect the output (e.g. the task’s script or bundler sets it to a fixed value); otherwise treat it like any other name. One finding per task config (Turbo task, or Nx target/targetDefault) that is missing declarations: list every missing name with its packages and up to 5 locations across all names, and set location.package only when a single package is affected.
caching/turbo-cache-disabled low Turbo task with cache: false that is deterministic by name: build, compile, bundle, lint, typecheck, check-types, format:check, or a unit test (test, test:unit, *:build, *:lint). Treat cache: false as deliberate — and do not flag — when the task is persistent: true; its name contains dev, start, serve, watch, deploy, release, publish, clean, db, migrat, seed, generate, extract, sync, upload, e2e, integration, or ends in :ci; or its env/passThroughEnv lists external-state vars (*DATABASE*, *DB_*, *REDIS*, *_URL, *TOKEN*, *SECRET*). Mention deliberately uncached tasks in reason, not as findings.
caching/unstable-hash high turbo installed: run TURBO_TELEMETRY_DISABLED=1 npx turbo run build --dry=json twice; any task whose hash differs between runs. Report the task and the inputs/environmentVariables that differ.
caching/volatile-input high non-negated task inputs or globalDependencies include build artifacts or machine-local files: dist, build, .turbo, .nx, *.tsbuildinfo, **/*.log, node_modules. Ignore negated globs (!…). Do not flag .env* files: including env files usually makes caches more correct.
caching/uncached-root-script low a root package.json script that runs tasks across packages bypassing the orchestrator: -r/--recursive, --workspaces/-ws, yarn workspaces foreach, lerna run. In repos without an orchestrator, say “consider adding Nx or Turborepo” in fix.

Steps

Section titled “Steps”
  1. Read turbo.json (Turbo v2 tasks and Turbo v1 pipeline, plus //#task root tasks and <pkg>/turbo.json overrides with "extends": ["//"]) and/or nx.json + every project.json / package.json#nx. For Nx, also read targetDefaults (including defaults keyed by executor), namedInputs, and legacy tasksRunnerOptions.*.options.cacheableOperations, and remember that Nx plugins (plugins in nx.json) can infer targets — if a target exists only via plugin inference, report rules that depend on its config as partial and say so.
  2. Apply the rules above. Quote the exact JSON in evidence (task name + its config object). Config-level findings (Turbo tasks, Nx targetDefaults/namedInputs) omit location.package; only set package when the problem is specific to one package (e.g. its own turbo.json/project.json, or an env read in its source).
  3. For build-inputs-include-tests, measure how often it matters with read-only git: git log --since="6 months ago" --name-only --format=%x00%H and count commits whose changed files are all test files (TEST pattern from scan.md). Report N of M commits (P%) changed only tests. Skip if the repo has no git history.
  4. unstable-hash runs only when turbo is installed; otherwise mark the check partial with reason turbo not installed; dry-run hash comparison skipped. Never run real tasks — only --dry=json.
  5. Write findings/caching.json.

Fix guidance

Section titled “Fix guidance”
  • missing-outputs (Turbo): "outputs": ["dist/**"] (add ".next/**", "!.next/cache/**" for Next.js).
  • missing-outputs (Nx): "outputs": ["{projectRoot}/lib"] matching the real out dir.
  • build-inputs-include-tests (Nx): "namedInputs": { "production": ["default", "!{projectRoot}/**/*.spec.ts", "!{projectRoot}/**/*.test.ts"] } and "build": { "inputs": ["production", "^production"] }.
  • build-inputs-include-tests (Turbo): "inputs": ["$TURBO_DEFAULT$", "!**/*.{test,spec}.*", "!**/__tests__/**"] ($TURBO_DEFAULT$ means all git-tracked files in the package). Apply it to every task in the build’s dependsOn chain that hashes sources (e.g. transit), or the build still rebuilds on test edits. Safe only if no package imports another package’s test files. Optional when the measured share of test-only commits is small.
  • undeclared-env: Turbo "env": ["API_URL"]; Nx "inputs": ["production", { "env": "API_URL" }].