turborepo

Turborepo

Root turbo.json task descriptions say what each task does; the why is here. Tags: boundaries.mdc; CI invariants: ../ops/ci.mdc.

Docs, in order: node_modules/turbo/schema.json (every key and futureFlags entry for the pinned version), node_modules/turbo/docs/ or pnpm turbo docs <query> (version-matched; the upstream-locked turborepo skill points there), Context7 /vercel/turborepo, then turborepo.dev.

Task graph

• transit is a no-op edge (transit-node pattern): check-types and test depend on transit, not ^check-types, so packages run in parallel yet invalidate when a dependency's source changes. App-to-app service bindings are not package dependencies: a Worker-name string binding reads nothing from the callee and needs no edge; whether typed cross-Worker RPC adds a <callee>#transit edge is decided with the first worker-* (service-bindings.mdc).
• check-types depends on types: the generated .cloudflare/types/index.d.ts is gitignored, so check-types cannot hash it as a tracked input and a fresh clone type-checks with no manual step. types is cached (input cloudflare.config.ts, output .cloudflare/types/**, hash also covers the lockfile's cf and workerd versions). No drift check: nothing generated is committed.
• build is deliberately not gated on check-types: check-types hashes tests/, so the edge made every test-only edit rebuild; with it gone and tests excluded from build inputs, a test-only edit keeps the build cached and out of --affected. The type gate lives in pnpm run ci, CD's turbo run check-types build, and the deploy / upload → check-types edges. So turbo run build alone never type-checks: name both (turbo run check-types build --filter=<app>...).
• deploy:check is cf deploy --prebuilt --dry-run as a cached task, depending on build only, with inputs: ["cloudflare.config.ts"] (an empty list would mean every file): it validates the Build Output, so its hash follows build and a test-only edit leaves it cached and out of --affected. It is not deploy -- --dry-run, because turbo hashes pass-through args into every task of the graph, so every dependency misses the cache.
• global.inputs is prepended to every task's inputs, not folded into one global hash, so a task can drop an entry with a negation glob. Never add OXC configs there: they belong to //#lint:* / //#format:check, and a global entry would invalidate check-types and build on a lint-only edit.
• //#hooks:test is uncached (guard-secret-commit shells out to git against the live index; the suite takes ~1 s) and sits in check and ci because the guards fail closed: a syntax error in a git guard denies every Bash command.
• App dev tasks are interruptible so turbo watch can restart them; front-app#dev runs with: ["worker-api#dev"] so a filtered front dev still has a gateway. worker-api#dev passes SENTRY_DSN through so a local secret can come from the shell as well as the app's .env: envMode: "strict" strips anything unlisted.
• global.passThroughEnv lists cf's CF_SEND_TELEMETRY, DO_NOT_TRACK, CLOUDFLARE_REGISTRY_PATH beside the WRANGLER_* entries, which stay for the Vitest pool and the Wrangler-only commands, and SKIP_ENV_FILES, which every app's vite.config.ts reads, so a new app inherits it (workers-config.mdc).
• deploy and upload pass XDG_CONFIG_HOME through: cf auth login stores the OAuth token under $XDG_CONFIG_HOME/cloudflare/. Stripped, cf misses the token and fails with No authentication token found.
• futureFlags.filterUsingTasks stays off: in 2.11.4 it makes --filter=...pkg follow task edges only, silently dropping dependent packages for the transit tasks, and CD's --filter='./apps/*...' relies on the package expansion; --affected already gets task precision from affectedUsingTaskInputs. Before re-enabling, confirm turbo run check-types test --filter=...@repo/dtos-common --dry=json still lists both apps.