{"post":{"slug":"turborepo-monorepo-setup-2026","title":"Turborepo monorepo setup in 2026: a real apps + packages walkthrough","excerpt":"Build a Turborepo monorepo from scratch in 2026 — apps, shared packages, caching, CI integration, and the gotchas most \"Hello World\" guides miss.","category":"code","date":"February 7, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">T</span>urborepo (now owned by Vercel) became the default monorepo tool for TypeScript/JavaScript projects in 2024 and consolidated that lead through 2026. The combination of a smart task graph and aggressive caching means you can run `turbo build` across 20 packages and only rebuild what changed. Here's how to set up a real monorepo, not a Hello World.\n\n## What changed in 2026\n\n- **Turborepo 3** released stable with major caching improvements and a cleaner config syntax.\n- **Remote caching free tier** generous enough for most indie projects (2GB).\n- **Pnpm 9** is the default package manager in templates — faster, less disk usage than npm/yarn.\n\n## The repo structure\n\n```\nmy-monorepo/\n  apps/\n    web/              # Next.js app\n    docs/             # Astro docs site\n    api/              # Cloudflare Worker\n  packages/\n    ui/               # React component library\n    db/               # Drizzle schema + queries\n    config/           # ESLint, TS, Prettier shared config\n    types/            # Shared TS types\n  turbo.json\n  pnpm-workspace.yaml\n  package.json\n```\n\nApps are leaves. Packages are shared and depend on each other but are not deployed. The split avoids accidentally importing dev tooling into runtime code.\n\n## The setup\n\n```bash\npnpm dlx create-turbo@latest my-monorepo\ncd my-monorepo\n```\n\nThen in `pnpm-workspace.yaml`:\n\n```yaml\npackages:\n  - \"apps/*\"\n  - \"packages/*\"\n```\n\nIn `turbo.json`:\n\n```json\n{\n  \"$schema\": \"https://turbo.build/schema.json\",\n  \"tasks\": {\n    \"build\": {\n      \"dependsOn\": [\"^build\"],\n      \"outputs\": [\".next/**\", \"dist/**\"],\n      \"env\": [\"NODE_ENV\"]\n    },\n    \"lint\": {},\n    \"test\": { \"dependsOn\": [\"^build\"] },\n    \"dev\": { \"cache\": false, \"persistent\": true }\n  }\n}\n```\n\n`^build` means \"build my dependencies first\". `cache: false` for dev avoids stale state.\n\n## Sharing packages\n\nIn `packages/ui/package.json`:\n\n```json\n{\n  \"name\": \"@my/ui\",\n  \"exports\": { \".\": \"./src/index.ts\" },\n  \"scripts\": {\n    \"build\": \"tsup src/index.ts --format esm,cjs --dts\",\n    \"dev\": \"tsup src/index.ts --format esm --watch\"\n  }\n}\n```\n\nIn `apps/web/package.json`:\n\n```json\n{\n  \"dependencies\": { \"@my/ui\": \"workspace:*\" }\n}\n```\n\n`workspace:*` tells pnpm \"use the local workspace package, not npm\". The `tsup` build emits ESM + CJS + types. Apps import as if it's an npm package.\n\n## Comparison: Turborepo vs alternatives\n\n| Tool | Best for | Skip if |\n| --- | --- | --- |\n| Turborepo 3 | TS/JS monorepos, Vercel-hosted | Polyglot needs |\n| Nx | Full-featured, Angular-heavy shops | You want lean |\n| Lerna | Legacy, package publishing | Building apps |\n| Yarn workspaces alone | Tiny monorepos, no task orchestration | Anything with build steps |\n| Pnpm workspaces alone | Same | Same |\n| Bazel | Massive scale, polyglot | Most teams |\n\n## Remote caching\n\nThe killer feature for teams. Turbo writes build artifacts to a shared cache. CI runs that fetch a cached build complete in seconds instead of minutes. Setup:\n\n```bash\nturbo login\nturbo link\n```\n\nNow CI shares the cache. A 5-minute build that already ran for someone else takes 5 seconds. For teams with even modest CI bills, this saves real money.\n\n## Common mistakes to avoid\n\n**Putting too much in shared packages.** Every shared package is a build dependency for downstream. Resist.\n\n**Forgetting `outputs` in `turbo.json`.** Tasks without declared outputs don't get cached.\n\n**Using `tsc` for both apps and packages.** Apps should use their bundler; packages use `tsup` or `unbuild` to emit ESM+CJS+DTS.\n\n**Skipping CI cache configuration.** Without remote caching, monorepo CI is slower than separate repos.\n\n**Mixing package managers.** Pick one (pnpm) and don't deviate.\n\n## FAQ\n\n**Can I migrate an existing repo to Turborepo?**\nYes. Most painful part is splitting code into packages. Start with `apps/` and add `packages/` as patterns emerge.\n\n**Does Turborepo work outside Vercel?**\nYes — works fine on Cloudflare Pages, AWS, self-hosted CI. Remote caching works against any S3-compatible store.\n\n**What about Bun's monorepo support?**\nBun handles workspaces fine. Combine with Turborepo for the task graph + caching layer.\n\n**Are there licensing concerns?**\nTurborepo is MIT. Remote caching service has free + paid tiers; self-host alternatives exist.\n\n## Where to go next\n\nFor related guides see [Bun vs Deno vs Node in 2026](/blog/bun-vs-deno-vs-node-2026), [TypeScript strict mode guide for 2026](/blog/typescript-strict-mode-guide-2026), and [Vitest vs Jest in 2026](/blog/vitest-vs-jest-2026).","hue":142,"metaTitle":"Turborepo Monorepo Setup Guide (2026)","metaDescription":"Real Turborepo monorepo from scratch in 2026 — apps, packages, caching, CI integration, and the patterns that work for production teams.","keywords":["turborepo 2026","turborepo tutorial","monorepo typescript","pnpm workspaces","turborepo caching","turbo remote cache","nextjs monorepo","shared packages monorepo","typescript monorepo setup","turborepo vs nx"],"tldr":["**Turborepo 3 has the best DX for TS/JS monorepos** — clean caching, smart task graph.","**Use pnpm workspaces for the package manager** — npm/yarn workspaces also work but pnpm is fastest.","**Remote caching is the killer feature** for teams — 5-10x CI speed-up on no-code-change runs.","**Plan your package structure before you start.** Refactoring a monorepo is painful."],"readTime":"3 min read","wordCount":659},"related":[{"slug":"how-to-set-up-a-monorepo-2026","title":"How to set up a monorepo in 2026","excerpt":"Monorepos let teams share code and coordinate releases without publishing packages. This guide covers tooling, workspace setup, and CI caching strategies for 2026.","category":"code","date":"March 16, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":309},{"slug":"nx-vs-turborepo-2026","title":"Nx vs Turborepo 2026: Which Monorepo Tool Wins","excerpt":"Nx and Turborepo both cache tasks to speed up monorepo builds, but they solve different problems. This guide compares caching, generators, and boundaries so you can pick the right tool in 2026.","category":"code","date":"August 7, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":308},{"slug":"monorepo-tooling-compared-2026","title":"Monorepo Tooling Compared: What You Actually Need","excerpt":"Monorepo tools solve task orchestration and caching, not repository layout. Here is what each tier provides and how to tell when you have outgrown the simple option.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":150}],"sameCategory":[{"slug":"bazel-build-explained-2026","title":"Bazel Explained: What Hermetic Builds Actually Cost","excerpt":"Bazel delivers reproducible, precisely cached builds and demands that you describe everything. Here is what you get, what it costs, and who should say no.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":145},{"slug":"graphql-federation-2026","title":"GraphQL Federation: One Graph, Many Teams","excerpt":"Federation composes independently-owned subgraphs into a single API. Here is what it solves, the operational cost it adds, and when a simpler gateway is enough.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":300},{"slug":"hermetic-builds-explained-2026","title":"Hermetic Builds Explained: Same Inputs, Same Output","excerpt":"A hermetic build depends only on declared inputs. Here is what that property gives you, the common leaks that break it, and how to move toward it incrementally.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":130},{"slug":"monorepo-tooling-compared-2026","title":"Monorepo Tooling Compared: What You Actually Need","excerpt":"Monorepo tools solve task orchestration and caching, not repository layout. Here is what each tier provides and how to tell when you have outgrown the simple option.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":150}],"newer":{"slug":"term-vs-whole-life-insurance-2026","title":"Term vs whole life insurance 2026: cost, when whole-life is sold vs needed","excerpt":"Term vs whole life insurance in 2026 — cost ratios, when whole-life is legitimately useful, and how to recognize when it's being sold to you.","category":"finance","date":"February 7, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":286},"older":{"slug":"30-day-money-saving-challenge-2026","title":"30-day money saving challenge 2026: day-by-day plan with realistic savings","excerpt":"A practical 30-day money saving challenge for 2026 — daily prompts, realistic dollar amounts, and the cumulative result a typical household sees.","category":"finance","date":"February 6, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":280}}