DEV Community

The Practical Developer
The Practical Developer

Posted on Originally published at practicaldevblog.blogspot.com

Turborepo Tutorial: Run Every Package With One Command

Quick answer

Turborepo is a build tool for JavaScript and TypeScript monorepos: one command builds every package in the right order and caches the results, so an unchanged package is never rebuilt. This post builds a small shop monorepo with a shared pricing package and a shop app, then shows the second build finishing in 17 milliseconds because the cache hits.

A small online shop in Karachi sells kurtas and dupattas. The shop app prices each order, the admin page prices refunds, and a checkout helper prices the cart, and each of the three copies the same discount rule: 10 percent off orders of Rs 10,000 or more, plus 5 percent tax. One day the discount changes to 15 percent, two copies get updated, and the third keeps charging the old price until a customer complains. A monorepo fixes the copying by putting the shared code in one package that every app imports. Turborepo makes that monorepo practical: it runs each package's build in dependency order and remembers the results.

What I would check before using it

My first check is whether the code is really shared. One app on its own has nothing to share, and Turborepo adds a layer it does not need. The moment a second app needs the same pricing or validation code, the monorepo starts earning its place. The pnpm: One Copy of Every Package, Shared Across Projects post shows how workspaces link those packages, and Turborepo sits on top of that layout.

My second check is how much time builds waste today. If every push rebuilds every package from scratch, the cache pays for itself. If the whole build already takes five seconds, the saving is real but small. The demo below turns 504 milliseconds into 17, which matters once the build grows to minutes.

My third check is who owns the cache. The local cache on one machine is free and needs no account. Sharing it across a team or CI needs the remote cache, a Vercel account and a token in CI. Somebody has to own that, or the remote cache quietly stops working.

My fourth check is the stack. Turborepo is built for JavaScript and TypeScript, and it works with npm, pnpm, and Yarn workspaces. A monorepo that is mostly Python or Go has other tools for the same job.

My verdict, as judgement: adopt Turborepo when two or more JavaScript packages share code and builds keep repeating unchanged work. Skip it for a single app. The recommendation flips the moment the shared package changes every day, because then everything rebuilds anyway.

One shop, two packages, and a cache that never hits

The monorepo has two packages. The shared package, @shop/pricing, holds one rule: 10 percent off orders of Rs 10,000 or more, plus 5 percent tax. The shop app imports it and prices Ayesha's order 1042, a kurta for Rs 8,900 and a dupatta for Rs 3,500. Each package has a build script that copies its source into dist/; a real package would bundle there, and the copy keeps the demo honest about what the cache stores.

{
  "name": "shop-monorepo",
  "private": true,
  "packageManager": "npm@10.9.4",
  "workspaces": ["apps/*", "packages/*"],
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

The first turbo.json has one gap: the build task declares no outputs.

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "lint": {},
    "test": {}
  }
}
Enter fullscreen mode Exit fullscreen mode

The dependsOn line makes the pricing package build before the shop app, so the app never reads a stale dist/.

// packages/pricing/src/index.js: the one shared pricing rule.
function orderTotal(items) {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.qty, 0);
  const discount = subtotal >= 10000 ? subtotal * 0.1 : 0;
  const afterDiscount = subtotal - discount;
  const tax = afterDiscount * 0.05;
  return {
    subtotal,
    discount,
    tax,
    total: afterDiscount + tax,
  };
}

function formatRs(amount) {
  return "Rs " + amount.toFixed(0);
}

module.exports = { orderTotal, formatRs };
Enter fullscreen mode Exit fullscreen mode
// apps/shop/src/index.js: one order, priced with @shop/pricing.
const { orderTotal, formatRs } = require("@shop/pricing");

const order = {
  id: 1042,
  customer: "Ayesha",
  items: [
    { name: "kurta", price: 8900, qty: 1 },
    { name: "dupatta", price: 3500, qty: 1 },
  ],
};

const result = orderTotal(order.items);
console.log(`Order ${order.id} for ${order.customer}:`);
console.log(`  subtotal ${formatRs(result.subtotal)}`);
console.log(`  discount ${formatRs(result.discount)}`);
console.log(`  tax      ${formatRs(result.tax)}`);
console.log(`  total    ${formatRs(result.total)}`);
Enter fullscreen mode Exit fullscreen mode

Here is the real output of the second build. Nothing changed since the first, yet Turborepo rebuilds both packages.

$ npx turbo run build
@shop/pricing:build: cache miss, executing 9decbb55038455ab
shop:build: cache miss, executing 3be8cdd4dc55f19c
shop:build: Order 1042 for Ayesha:
shop:build:   subtotal Rs 12400
shop:build:   discount Rs 1240
shop:build:   tax      Rs 558
shop:build:   total    Rs 11718
 Tasks:    2 successful, 2 total
Cached:    0 cached, 2 total
  Time:    504ms
Enter fullscreen mode Exit fullscreen mode

The total is right: Rs 12,400 subtotal, Rs 1,240 discount, Rs 558 tax, Rs 11,718 to pay. But the cache is useless, because Turborepo only caches the files a task declares as outputs, and none are declared here. The fix is one line in turbo.json.

"build": {
  "dependsOn": ["^build"],
  "outputs": ["dist/**"]
}
Enter fullscreen mode Exit fullscreen mode

The first build after the fix still misses the cache, because changing turbo.json changes the fingerprint. The next build is the payoff.

$ npx turbo run build
@shop/pricing:build: cache hit, replaying logs a4e9e13698507f36
shop:build: cache hit, replaying logs cc12f6842e89a6b0
shop:build: Order 1042 for Ayesha:
shop:build:   subtotal Rs 12400
shop:build:   discount Rs 1240
shop:build:   tax      Rs 558
shop:build:   total    Rs 11718
 Tasks:    2 successful, 2 total
Cached:    2 cached, 2 total
  Time:    17ms >>> FULL TURBO
Enter fullscreen mode Exit fullscreen mode

Same order, same total, 17 milliseconds instead of 504, because Turborepo restored both dist/ folders and replayed the logs from the cache. In a real shop the app would be a front end built with Vite Explained: Why Development Got Instant and the pricing build would bundle with esbuild: Bundle JavaScript in Milliseconds, Not Seconds, but Turborepo would run and cache those builds the same way.

Common mistakes and how to fix them

First, forgetting outputs, the bug from the demo. The symptom is cache miss on every build and 0 cached even when nothing changed. The fix is to declare "outputs": ["dist/**"] on the task, so Turborepo has something to store.

Second, forgetting dependsOn: ["^build"]. The symptom is the shop app building before the pricing package, so it reads a stale or missing dist/ and fails with Cannot find module '@shop/pricing'. The fix is the dependsOn line.

Third, adding a package that Turborepo never sees. The symptom is a new folder under packages/ that never appears in the Packages in scope line, so its build never runs. The fix is to check the workspaces array in the root package.json; the npm Explained: The Package Manager Behind JavaScript post covers how workspaces link packages.

Fourth, running turbo from inside apps/shop instead of the repo root. The symptom is an error that no turbo.json was found, or only one package building. The fix is to run every turbo command from the folder holding turbo.json.

Frequently Asked Questions

Is Turborepo a package manager? No. It runs on top of npm, pnpm, or Yarn workspaces, which install and link the packages. Turborepo only runs the tasks, in order, with a cache.

Do I need Vercel to use Turborepo? No. The local cache works with no account and no setup, and the demo above uses it. The remote cache is optional, for sharing entries between machines and CI.

How is Turborepo different from Nx? Both orchestrate monorepo tasks, and Nx adds generators, plugins, and project graphs. Turborepo is the smaller tool: tasks, ordering, and caching, with less to learn. Pick Nx for the generators; pick Turborepo when the cache is the whole job.

What happens when I change one file? Only the package that changed and the packages that depend on it rebuild. Everything else replays from the cache, which is why a one-line change in a big monorepo stays fast.

What to remember

  • Shared code lives in one package that every app imports, instead of being copied.
  • turbo run build builds packages in dependency order, with dependsOn: ["^build"].
  • Declare "outputs": ["dist/**"], or Turborepo has nothing to cache.
  • A cache hit restores outputs and replays logs; the demo went from 504ms to 17ms.
  • Local cache needs no account; remote cache is optional, for teams and CI.

Where this leaves you

Turborepo earns its place the day a second app copies a rule the first app already has, and the builds start repeating work nobody changed. The demo proved the two things that matter: the shared pricing package priced order 1042 correctly at Rs 11,718, and the cache turned a 504 millisecond rebuild into a 17 millisecond replay. Start with one shared package, one turbo.json, and the local cache, then add the remote cache when the team grows. A build that only does new work is a build that stays fast.

Further reading

Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.

Top comments (0)