Turborepo usage

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Quick reference

# Cached single-tasks (replace plain npm equivalents when you want cache reuse)
npm run turbo:typecheck      # = turbo run typecheck       (~9 min cold, ~350 ms cache hit)
npm run turbo:lint           # = turbo run lint:ci         (~88 s cold, ~5 s cache hit)
npm run turbo:format:check   # = turbo run format:check
npm run turbo:test:unit      # = turbo run test:unit       (~3.7 min cold)
npm run turbo:build          # = turbo run build           (depends on //#typecheck in turbo.json)
npm run turbo:validate       # = turbo run format:check typecheck lint:ci build (same as npm run validate)

# Inspect cache state without running anything
npm run turbo:cache:status

# Force a re-run, ignoring cache (useful when debugging cache-key mistakes)
npx turbo run typecheck --force

# See what tasks would run, with hashes
npx turbo run typecheck --dry-run

​

Why Turborepo here

• A PR that only changes files outside task inputs (e.g. many specs/ or docs/ markdown-only edits) can see format/typecheck/lint/build cache hits and finish much faster once caches are warm.
• A PR touching only src/cores/hr/* invalidates typecheck, lint:ci, test:unit, build — but not format:check (different input set).
• The cache key includes tsconfig*.json, package-lock.json, the relevant config files (vite.config.ts, vitest.config.ts, biome.json, eslint.config.js), and the input files themselves.

​

Configuration

• globalDependencies lists tracked config files that, if changed, must invalidate every cache entry (tsconfig*.json, vite.config.ts, vitest.config.ts, biome.json, eslint.config.js, package*.json). .env / .env.* are not global deps — they are listed on the //#build task inputs so local env churn does not bust typecheck/lint/format caches. If a change should invalidate every task, add it here deliberately.
• globalEnv lists env vars whose values affect every task (NODE_ENV, CI, VERCEL_PROJECT_ID).
• Each task declares its inputs explicitly. We do not use the default “everything in the workspace” input set — that would cause spurious cache invalidations on docs/spec edits.
• //#build declares dependsOn: ["//#typecheck"] so turbo run build always waits on typecheck; a cache hit on typecheck satisfies the dependency without re-running it.
• dev is cache: false, persistent: true.

​

Sandboxing caveats

1. Run npm run turbo:cache:status before merging PRs that change input declarations to confirm hashes change as expected.
2. When in doubt, npx turbo run <task> --force to bypass cache.
3. If we hit recurring cache poisoning, that is the trigger to revisit Nx (which provides task sandboxing).

​

Vercel Remote Cache (optional; recommended)

1. In the Vercel dashboard, open each project that runs Turborepo (encoreos_dev, encoreos_prod, and any future encoreos-public project).
2. Project Settings → General → “Build & Development Settings” → ensure “Remote Cache” is enabled (on by default for eligible plans).
3. Locally: npx turbo login then npx turbo link once per workstation (token in ~/.turbo/config.json).
4. In GitHub: add repository secrets TURBO_TOKEN and TURBO_TEAM (or TURBO_TEAM as a variable if you prefer non-secret team slug). .github/workflows/build.yml passes them as job-level env so every npx turbo run … step can upload/download remote artifacts.
5. Verify cache hits: open a PR, push an empty commit, and compare Turbo output on the second run — or run locally:
   npx turbo run typecheck --summarize
   
   Remote hits show as remote cache reads in the summary (exact wording varies by Turbo version).

​

Wiring into CI

- name: Cache Turborepo local cache
  uses: actions/cache@v5
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      turbo-${{ runner.os }}-

- name: Typecheck via Turborepo
  run: npx turbo run typecheck

- name: Lint via Turborepo
  run: npx turbo run lint:ci

- name: Build via Turborepo
  run: npx turbo run build

​

Vercel Remote Cache in CI

​

Measured wins on this branch

​

Troubleshooting

​

See also

• turbo.json — task definitions
• docs/recommendations/DEV_VELOCITY_AND_ARCHITECTURE_PLAN_2026-04-22.md — Phase 1 plan
• Turborepo docs
• Vercel Remote Cache docs