What You’re Doing

The workspace has four packages (analytics, users, ui, shared) and a dashboard app, but there is no build orchestration. Running pnpm -r build rebuilds everything every time, even unchanged packages. You’re going to create a turbo.json configuration and wire up Turborepo so builds are cached, dependency-aware, and fast.

Why It Matters

Without a build orchestrator, every CI run and every local build starts from scratch. In a monorepo with 5 packages that takes a few seconds; in a monorepo with 50 packages it takes minutes. Turborepo’s content-aware hashing means a build that has already succeeded with the same inputs is never repeated. The second build is free. Changing one leaf package only rebuilds its dependents, not the entire graph. This is the tool that makes monorepos viable at scale.

Prerequisites

• Node.js 20+
• pnpm 9+

Setup

You should be continuing from where Exercise 3 left off. If you need to catch up:

git checkout 03-monorepo-start
pnpm install

Step 1: Feel the Problem

Run the build without Turborepo to understand what you’re fixing.

1. Run the build across all workspace packages:

pnpm -r build

Note the output — every package builds, sequentially. Note how long it takes.

2. Run it again immediately, without changing anything:

pnpm -r build

Same time. Same output. Every package rebuilt even though nothing changed. pnpm’s --recursive flag has no caching — it just runs the build script in every package that has one.

Checkpoint

You’ve run pnpm -r build twice and both runs took roughly the same time. There is no caching, no dependency ordering, no parallelization.

Step 2: Install Turborepo and Create turbo.json

Install Turborepo as a dev dependency at the workspace root:

pnpm add -Dw turbo

Create a turbo.json file at the root of the repository:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "typecheck": {
      "dependsOn": ["^typecheck"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["^build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

What Each Field Means

• "dependsOn": ["^build"] — The ^ prefix means “run this task in my dependencies first.” Before @pulse/analytics builds, Turborepo ensures @pulse/ui and @pulse/shared have already built. Without the caret, dependsOn: ["build"] would mean “run build in this package first” (a self-dependency, usually not what you want).

• `“outputs”: [“dist/”]`** — Tells Turborepo which files to cache. After a successful build, it hashes the inputs (source files, dependencies, env vars) and stores the outputs. On the next run with the same inputs, it replays the cached outputs instead of running the build again.

• "lint": {} — No dependsOn, no outputs. Linting each package is independent — you don’t need to lint dependencies first, and there’s nothing to cache beyond the pass/fail result.

• "cache": false — The dev task should never be cached. It’s a long-running process (a dev server), not a one-shot command.

• "persistent": true — Tells Turborepo that dev is a long-running process that doesn’t exit. Without this, Turborepo would wait for it to finish before running dependent tasks (which would hang forever).

Step 3: Update Root package.json Scripts

Open the root package.json and update the scripts to use Turborepo:

{
  "scripts": {
    "build": "turbo build",
    "typecheck": "turbo typecheck",
    "lint": "turbo lint",
    "test": "turbo test",
    "dev": "turbo dev"
  }
}

Now pnpm build delegates to Turborepo instead of running scripts directly.

Step 4: Run Turborepo for the First Time

1. Run the build through Turborepo:

pnpm turbo build

Watch the output. Turborepo prints each task as it runs, showing the dependency ordering:

Every task says “cache miss” because this is the first run — there is no cache yet.

2. Run it again immediately:

pnpm turbo build

Now the output is different:

Every task shows “cache hit.” The total time drops to under a second. FULL TURBO means every single task was served from cache.

Checkpoint

pnpm turbo build on a clean cache builds everything. The second run shows FULL TURBO and completes in under a second.

Step 5: Observe Partial Rebuilds

Now change something and watch Turborepo rebuild only what’s necessary.

1. Open packages/ui/src/button.tsx and make a small change — add a comment at the top of the file:

// Updated button styling

2. Save the file and run the build again:

pnpm turbo build

Look at the output carefully:

@pulse/shared and @pulse/legacy are cache hits — they didn’t change and have no dependency on @pulse/ui. But @pulse/ui is a cache miss (you changed it), and everything that depends on @pulse/ui also rebuilds: @pulse/analytics, @pulse/users, and @pulse/dashboard.

3. Revert your change to packages/ui/src/button.tsx (remove the comment) and run pnpm turbo build again. It should be FULL TURBO — the files are back to the cached state.

Checkpoint

After changing packages/ui, only @pulse/shared shows a cache hit. Everything downstream of @pulse/ui rebuilds. After reverting, the cache is restored.

Step 6: Examine the Dependency Graph

Turborepo can visualize the task graph it constructs.

1. Generate the graph:

pnpm turbo build --graph=graph.html

This generates an HTML file with a visualization of the dependency graph. Open graph.html in your browser. You should see:

• @pulse/shared at the bottom (no dependencies)
• @pulse/ui one level up (depends on @pulse/shared)
• @pulse/analytics and @pulse/users at the next level (both depend on @pulse/ui and @pulse/shared)
• @pulse/dashboard at the top (depends on everything)

2. Try the filter with the graph:

pnpm turbo build --filter=@pulse/analytics... --graph=graph-analytics.html

This generates a graph showing only the subgraph relevant to @pulse/analytics and its dependencies.

Checkpoint

You can visualize the dependency graph and identify which packages are upstream and downstream of any given package.

Stretch Goals

• Filter builds: Run pnpm turbo build --filter=@pulse/analytics... to build only analytics and its dependencies. Compare the task count to a full build.
• Dry run: Run pnpm turbo build --dry-run=json to see exactly what Turborepo would execute without running anything. Inspect the JSON output to understand the hash computation.
• Environment variables: Add an environment variable to the build task’s env key in turbo.json and observe that changing the variable invalidates the cache.

Solution

If you need to catch up, the completed state for this exercise is available on the 04-typescript-start branch:

git checkout 04-typescript-start
pnpm install

What’s Next

You have cached, dependency-aware builds. But TypeScript still checks each package independently — there’s no incremental type checking across package boundaries. Changing a type in @pulse/shared forces a full recheck of every package. In the next exercise, you’ll add composite: true and project references so TypeScript can do incremental cross-package type checking.