Skip to content
Learni
View all tutorials
Architecture

How to Configure Turborepo for a Monorepo in 2026

12 minINTERMEDIATE
MonorepoTurborepo
Lire en français

Introduction

Turborepo enables management of complex monorepos with fast builds through caching and parallel task execution. In 2026, it remains the reference tool for teams wanting to scale applications without sacrificing performance. This tutorial walks you through configuring a monorepo with multiple applications and shared packages step by step.

Prerequisites

  • Node.js 20+
  • npm or pnpm
  • Basic knowledge of TypeScript and monorepos
  • A terminal and code editor

Initialize the Monorepo

terminal
npx create-turbo@latest my-turborepo --yes
cd my-turborepo

This command creates the base structure with an apps folder and packages folder. The --yes flag accepts defaults for a quick start.

Configure turbo.json

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

The turbo.json file defines the pipelines. The ^build dependencies ensure packages are built before apps that depend on them.

Add a Shared Package

packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    "./button": "./src/button.tsx"
  },
  "scripts": {
    "build": "tsc",
    "lint": "eslint ."
  }
}

This package exports reusable components. The @repo scope simplifies imports across workspaces.

Update Root Scripts

package.json
{
  "name": "my-turborepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

Root scripts delegate execution to Turbo to benefit from automatic caching and parallelism.

Run the Full Build

terminal
npm run build

Turbo runs tasks in parallel, reuses the cache when possible, and displays a clear summary of results.

Best Practices

  • Always declare outputs in turbo.json to enable caching
  • Use @repo scopes for internal packages
  • Configure persistent tasks (dev) with persistent: true
  • Run turbo with --filter to target specific packages
  • Regularly update the Turbo version

Common Errors to Avoid

  • Forgetting to declare ^build dependencies in turbo.json
  • Not excluding node_modules from outputs
  • Running npm commands directly instead of turbo
  • Ignoring corrupted cache errors (use turbo clean)

Going Further

Explore our advanced monorepo and Turborepo courses at Learni Group.