Turborepo for Node

Turborepo orchestrates workspace tasks with remote caching so unchanged packages skip rebuilds in CI and locally.

Recipe

Quick-reference recipe card - copy-paste ready.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

npx turbo run build test typecheck

When to reach for this:

• Monorepo with 3+ packages and repeated build/test in CI.
• Shared libs must compile before apps typecheck.
• You want cache hits across developers and CI runners.

Working Example

platform/
  turbo.json
  package.json          # workspaces
  apps/
    api/package.json
  packages/
    shared/package.json

// package.json (root)
{
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "dev": "turbo run dev --parallel"
  },
  "devDependencies": {
    "turbo": "^2.3.0",
    "typescript": "^5.6.0"
  }
}

// packages/shared/package.json
{
  "name": "@acme/shared",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "test": "node --import tsx --test"
  }
}

// apps/api/package.json
{
  "name": "@acme/api",
  "dependencies": { "@acme/shared": "workspace:*", "fastify": "^5.0.0" },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "dev": "tsx watch src/server.ts",
    "test": "node --import tsx --test"
  }
}

npm install
npx turbo run build --filter=@acme/api...

What this demonstrates:

• ^build runs dependency package builds before dependents.
• --filter=@acme/api... includes the API and its workspace dependencies.
• outputs tells Turbo what to cache between runs.

Deep Dive

How It Works

• Turbo hashes task inputs (source, env vars, dependencies) and restores outputs from cache on cache hit.
• dependsOn builds a DAG; test waits for build artifacts.
• Remote cache (Vercel or self-hosted) shares hits across CI machines.
• dev tasks are typically persistent: true and not cached.

Task Configuration

TypeScript Notes

{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "typecheck": { "dependsOn": ["^build"] }
  }
}

• Separate typecheck from build if you want faster CI jobs that skip emit when only checking types.
• Ensure each package tsconfig emits to dist/ consistently for cache paths.

Gotchas

• Missing outputs - Turbo caches nothing useful; every build reruns fully. Fix: declare dist/** per compile task.
• Wrong filter syntax - @acme/api alone skips dependency builds. Fix: use @acme/api... (three dots) for dependents chain.
• Caching tests with side effects - Tests hitting real DB get false green from cache. Fix: exclude integration tests from cached tasks or use unique inputs.
• Env secrets in hash - env lists bust cache when tokens change. Fix: only list env vars that affect build output.
• dev task cached by mistake - Watch mode should not cache. Fix: "persistent": true and no outputs on dev.

Alternatives

FAQs

npx turbo run dev --filter=@acme/api

Related

• Workspaces & Monorepos - workspace linking
• Multi-Service Monorepo - deployable boundaries
• Nx for Node Backends - alternative orchestration

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.