2026-09-26 · 11 min
Monorepo in Production: Turborepo vs Nx, Build Caching, and What Nobody Tells You
Three months into a project with twelve packages in a single repo, your CI pipeline starts taking fourteen minutes per pull request. That is the moment most teams reach for a monorepo build tool — and also the moment most teams pick the wrong one for their situation.
I have set up monorepos under deadline pressure for clients in BSD Serpong and remote teams across three time zones. The patterns that actually hold up in production are different from what the official docs optimize for.
Why monorepo build tooling matters more than the repo structure
The folder structure of a monorepo is the easy part. Whether you put apps in apps/ and packages in packages/ or use services/ and libs/ — it barely matters. What matters is the task graph: which tasks depend on which, what gets cached, and what gets skipped when nothing changed.
Without a proper task orchestrator, every CI run rebuilds everything. With one, a change to packages/ui only rebuilds apps/web (which depends on it) and skips apps/admin if it does not import from packages/ui. That is the value proposition.
Turborepo and Nx both solve this. They differ in how much they want to own.
Turborepo: simple, fast, opinionated about little
Turborepo is configuration-light. The entire orchestration lives in turbo.json:
{
"$schema": "https://turbo.build/schema.json",
"ui": "tui",
"tasks": {
"build": {
"dependsOn": ["^build"],
"inputs": ["src/**", "package.json", "tsconfig.json"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
},
"test": {
"dependsOn": ["build"],
"inputs": ["src/**", "test/**", "jest.config.*"],
"outputs": []
},
"lint": {
"inputs": ["src/**", ".eslintrc*", "eslint.config.*"],
"outputs": []
},
"dev": {
"cache": false,
"persistent": true
}
}
}
The ^build syntax means “run build in all dependencies first.” This is how Turborepo knows to build packages/ui before apps/web.
One footgun that cost me two hours: the outputs array. If you specify outputs incorrectly — or too broadly — the remote cache will store files you do not need and, worse, restore them over files that should be different. If your build task writes to dist/ but you declare outputs: ["dist/**", "**/*.tsbuildinfo"], you might get cache hits that restore a stale .tsbuildinfo from a different package. Be precise.
Another non-obvious behavior: inputs defaults to all tracked files in the package if you omit it. That means adding a README.md to a package invalidates its build cache. Always declare inputs explicitly in production setups.
Setting up remote caching with a self-hosted store
Turborepo’s hosted cache at vercel.com/speed works well. But if your organization cannot push build artifacts to a third-party cloud — common in fintech clients I work with — you need self-hosted.
turborepo-remote-cache is an open-source server that implements the Turborepo cache API and backs onto S3 or local storage:
# docker-compose.yml (run this on your own infrastructure)
services:
turbo-cache:
image: ducktors/turborepo-remote-cache:latest
environment:
STORAGE_PROVIDER: s3
S3_ACCESS_KEY: ${S3_ACCESS_KEY}
S3_SECRET_KEY: ${S3_SECRET_KEY}
S3_REGION: ap-southeast-1
S3_BUCKET: your-turbo-cache-bucket
TURBO_TOKEN: ${TURBO_TOKEN}
ports:
- "3000:3000"
In your repo root .turbo/config.json:
{
"teamid": "team_yourorg",
"apiurl": "https://turbo-cache.internal.yourcompany.com"
}
Run with the token:
TURBO_TOKEN=your-token turbo run build --team=team_yourorg
Cache hit rates above 80% are achievable once you get the inputs declarations right. Below 60% usually means you have over-broad inputs or missing env declarations.
Nx: more power, more surface area
Nx takes a different approach. It builds a full project graph from your workspace and lets you run tasks with much finer control. The tradeoff: there is more to configure, more concepts to learn, and more opinions baked in.
For a TypeScript monorepo with Nx:
// nx.json
{
"targetDefaults": {
"build": {
"dependsOn": ["^build"],
"inputs": ["production", "^production"],
"cache": true
},
"test": {
"inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
"cache": true
},
"lint": {
"inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
"cache": true
}
},
"namedInputs": {
"default": ["{projectRoot}/**/*", "sharedGlobals"],
"production": [
"default",
"!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
"!{projectRoot}/tsconfig.spec.json"
],
"sharedGlobals": ["{workspaceRoot}/babel.config.json"]
}
}
The namedInputs system is Nx’s answer to Turborepo’s inputs. It is more expressive — you can define production inputs that exclude test files so a change to a .spec.ts file does not invalidate your build cache. Turborepo cannot do this without manually listing every exclusion inline.
Where Nx genuinely pulls ahead: affected commands.
# Only run build and test for packages changed since main
nx affected -t build test --base=main --head=HEAD
This is more than Turborepo’s dependency graph — Nx tracks which packages are affected by your changes and skips everything else entirely, not just cached results. In a monorepo with 40+ packages, this difference is significant: Turborepo checks cache for all packages; Nx does not even look at unaffected ones.
CI pipeline: putting it together
Here is a GitHub Actions workflow that uses Turborepo with remote caching:
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # needed for Nx affected; safe to include for Turbo too
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 22
cache: "pnpm"
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Build, test, lint
run: pnpm turbo run build test lint
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: team_yourorg
TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_SIGNATURE_KEY }}
One thing worth calling out: fetch-depth: 0 is required for Nx affected calculations. Without full git history, Nx cannot determine which commits introduced which changes. For Turborepo it does not matter, but including it does not hurt.
The outputs and inputs discipline problem
Most monorepo pain in production is not a tooling problem — it is a discipline problem around declaring inputs and outputs accurately.
Real example: a team I worked with had a generate task that wrote files to src/generated/. Their build task depended on generate, but src/generated/ was not listed in build’s inputs. Result: the build cache was keyed without including generated files, so a change to the generator that produced different output still returned a cache hit with stale generated content. Took three days to trace.
The fix is straightforward once you understand the model:
{
"tasks": {
"generate": {
"inputs": ["scripts/generate.ts", "schemas/**/*.json"],
"outputs": ["src/generated/**"]
},
"build": {
"dependsOn": ["^build", "generate"],
"inputs": ["src/**", "!src/generated/**", "package.json", "tsconfig.json"],
"outputs": ["dist/**"]
}
}
}
generate is a dependency of build, so Turborepo runs it first. The outputs of generate are automatically treated as part of the cache artifact. The !src/generated/** exclusion in build’s inputs prevents double-counting — the generated files’ influence flows through the generate task’s cache key, not directly through build’s.
Turborepo vs Nx: the honest comparison
| Turborepo | Nx | |
|---|---|---|
| Config overhead | Low | Medium-High |
| Learning curve | ~1 day | ~1 week |
| Affected commands | No (uses cache misses) | Yes (true affected) |
| Distributed execution | Via Vercel Remote Cache | Nx Cloud / DTE |
| Code generation | Not built-in | Generators + executors |
| Plugin ecosystem | Minimal | Large |
| Large monorepo (50+ packages) | Works, but slower to reason about | Better fit |
| Small-to-medium monorepo | Excellent fit | Overkill for most |
For most teams shipping a web app plus a handful of shared packages, Turborepo is the right call. You will be productive in an afternoon. Nx earns its complexity at scale — when you have multiple app teams, diverse languages, and need orchestration that goes beyond “run these tasks in dependency order.”
What actually matters for production
Remote cache hit rate is your north star metric. Instrument it. Log it. Alert when it drops below a threshold.
The other thing nobody mentions: cache poisoning from environment variables. If your build reads process.env.NEXT_PUBLIC_API_URL but you do not declare it in turbo.json’s env array, builds from different environments (staging, production) can share cache artifacts that should not be shared. This causes the subtle class of bug where your production build has staging URLs baked in because the cache was warmed on a staging runner.
{
"tasks": {
"build": {
"env": ["NODE_ENV", "NEXT_PUBLIC_API_URL", "NEXT_PUBLIC_APP_VERSION"],
"outputs": [".next/**", "!.next/cache/**"]
}
}
}
Declaring env in turbo.json makes those variables part of the cache key. Different values produce different cache entries. This is not optional in any production setup.
The setup that works
For a TypeScript monorepo in production in 2026: pnpm workspaces for dependency management, Turborepo for task orchestration, self-hosted turborepo-remote-cache on a VPS if you cannot use Vercel’s hosted service, and strict inputs/outputs/env declarations verified in CI with --dry-run on every pipeline change.
The monorepo tool is not the hard part. The discipline of accurately modeling your task graph is.
Ditulis oleh Reza Pradipta