Monorepo Architecture: Turborepo, Nx, pnpm Workspaces, and Build Optimization

Master monorepo architecture with Turborepo, Nx, and pnpm workspaces. Learn build optimization, workspace management, and scaling strategies for large JavaScript projects.

Introduction
What is a Monorepo?
Monorepo vs Multi-repo: When to Use Each
pnpm Workspaces: Foundation of Modern Monorepos
Turborepo: High-Performance Build System
Nx: Enterprise-Grade Monorepo Tools
Build Optimization Strategies
Dependency Management in Monorepos
Task Orchestration and Caching
Code Sharing and Internal Packages
Testing Strategies in Monorepos
Common Pitfalls and Anti-Patterns
Best Practices
Conclusion

Introduction

As JavaScript applications grow in complexity and teams scale, managing multiple related projects becomes increasingly challenging. Traditional multi-repo approaches, where each project lives in its own repository, create friction when sharing code, coordinating changes, and maintaining consistency across projects. Monorepos—single repositories containing multiple related projects—have emerged as a powerful solution for managing large-scale codebases.

Monorepos offer significant advantages: shared code becomes trivial, refactoring across projects is easier, dependency management is centralized, and tooling can be consistent across all projects. However, without proper tooling, monorepos can become slow, difficult to navigate, and hard to maintain. Modern tools like Turborepo, Nx, and pnpm workspaces have revolutionized monorepo management by providing intelligent caching, parallel task execution, and efficient dependency resolution.

This comprehensive guide will teach you everything you need to know about monorepo architecture. You’ll learn how to set up and manage monorepos using pnpm workspaces, optimize builds with Turborepo, leverage enterprise features with Nx, and implement best practices for scaling your development workflow. Whether you’re managing a handful of packages or hundreds, you’ll discover strategies to keep your monorepo fast, maintainable, and developer-friendly.

What is a Monorepo?

A monorepo (monolithic repository) is a single version control repository that contains multiple related projects or packages. Unlike traditional multi-repo setups where each project has its own repository, a monorepo consolidates everything into one place, enabling easier code sharing, unified versioning, and coordinated changes across projects.

Core Characteristics

Single Repository: All projects live in one Git repository, sharing the same version history and branching strategy.

Multiple Packages: The repository contains multiple independent packages or applications that can be developed, tested, and deployed separately.

Shared Dependencies: Common dependencies are managed at the root level, reducing duplication and ensuring version consistency.

Unified Tooling: Build tools, linting rules, testing frameworks, and other development tools are shared across all packages.

Real-World Examples

Many major companies and open-source projects use monorepos:

Google: Uses a massive monorepo containing millions of files
Facebook/Meta: Manages React, React Native, and related tools in a monorepo
Microsoft: TypeScript and many Microsoft projects use monorepos
Babel: All Babel plugins and tools are in a single monorepo
Jest: Jest and its ecosystem live in one repository

Benefits of Monorepos

✅ Code Sharing: Share utilities, types, and components across packages without publishing to npm

✅ Atomic Changes: Make changes across multiple packages in a single commit

✅ Consistent Tooling: Use the same build tools, linting rules, and testing frameworks everywhere

✅ Easier Refactoring: Refactor code across packages with IDE support and type safety

✅ Simplified Dependency Management: Manage dependencies in one place, avoid version conflicts

✅ Better Developer Experience: Navigate between related code easily, understand dependencies visually

Challenges of Monorepos

⚠️ Build Performance: Without optimization, building all packages can be slow

⚠️ Repository Size: Large repositories can be slow to clone and navigate

⚠️ Access Control: Harder to restrict access to specific parts of the codebase

⚠️ CI/CD Complexity: Need to determine which packages changed and what to rebuild

Modern monorepo tools address these challenges through intelligent caching, incremental builds, and change detection.

Monorepo vs Multi-repo: When to Use Each

Choosing between a monorepo and multi-repo architecture depends on your project’s needs, team structure, and scale. Understanding the trade-offs helps you make the right decision.

When to Use a Monorepo

Related Projects: Multiple projects that share code, types, or utilities benefit from a monorepo. For example, a web app, mobile app, and shared component library.

Coordinated Releases: When you need to release multiple packages together or maintain version compatibility across packages.

Small to Medium Teams: Teams that work across multiple projects benefit from easier collaboration and code sharing.

Rapid Iteration: When you frequently need to make changes across multiple packages simultaneously.

Shared Tooling: When you want consistent build tools, linting, and testing across all projects.

When to Use Multi-repo

Independent Projects: Projects that don’t share code or have different release cycles work better in separate repositories.

Different Teams: When different teams own different projects and want independent workflows.

Open Source Libraries: Public libraries that are consumed independently benefit from separate repositories.

Access Control: When you need strict access control per project (though monorepos can use path-based permissions).

Repository Size: When the combined size would make the repository unwieldy.

Hybrid Approach

Many organizations use a hybrid approach: a monorepo for related projects and separate repositories for independent ones. For example, keeping all frontend applications in one monorepo while maintaining backend services in separate repositories.

pnpm Workspaces: Foundation of Modern Monorepos

pnpm workspaces provide the foundation for modern monorepo setups. pnpm’s efficient disk usage, strict dependency resolution, and workspace features make it an excellent choice for monorepos. If you’re new to pnpm, check out our complete package manager comparison to understand why pnpm excels in monorepo scenarios.

Setting Up pnpm Workspaces

Creating a pnpm workspace is straightforward. Start by creating a pnpm-workspace.yaml file at the root of your repository:

packages:
  - "packages/*"
  - "apps/*"
  - "tools/*"

This configuration tells pnpm to treat all directories matching these patterns as workspace packages. Your directory structure might look like this:

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── pnpm-lock.yaml
├── packages/
│   ├── shared-utils/
│   │   └── package.json
│   ├── ui-components/
│   │   └── package.json
│   └── types/
│       └── package.json
├── apps/
│   ├── web-app/
│   │   └── package.json
│   └── admin-panel/
│       └── package.json
└── tools/
    └── eslint-config/
        └── package.json

Root package.json Configuration

The root package.json manages workspace-wide dependencies and scripts:

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "dev": "pnpm --filter './apps/*' dev",
    "build": "pnpm --filter './packages/*' build",
    "test": "pnpm --filter './packages/*' test",
    "lint": "pnpm --filter './packages/*' lint"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "eslint": "^8.55.0",
    "prettier": "^3.1.0"
  }
}

Package Configuration

Each workspace package has its own package.json. Use workspace protocol (workspace:*) to reference other packages:

{
  "name": "@my-org/ui-components",
  "version": "1.0.0",
  "dependencies": {
    "@my-org/shared-utils": "workspace:*",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "typescript": "^5.3.0"
  }
}

Installing Dependencies

pnpm provides powerful filtering options for managing dependencies:

# Install dependency in root (shared across all packages)
pnpm add -w -D typescript

# Install dependency in specific package
pnpm add react --filter @my-org/web-app

# Install dependency in all packages matching pattern
pnpm add lodash --filter './packages/*'

# Install all workspace dependencies
pnpm install

Running Scripts Across Workspaces

pnpm’s --filter flag enables running scripts across multiple packages:

# Run script in specific package
pnpm --filter @my-org/web-app dev

# Run script in all packages
pnpm --filter './packages/*' build

# Run script in packages that depend on another package
pnpm --filter '@my-org/ui-components...' test

# Run script with topological order (dependencies first)
pnpm --filter './packages/*' --recursive build

Workspace Protocol Benefits

The workspace:* protocol ensures packages always use the local workspace version:

{
  "dependencies": {
    "@my-org/shared-utils": "workspace:*"
  }
}

This automatically resolves to the local package, making development seamless. When publishing, pnpm can replace workspace:* with actual version numbers.

Turborepo: High-Performance Build System

Turborepo is a high-performance build system for JavaScript and TypeScript monorepos. Built by the team behind Vercel, Turborepo focuses on speed through intelligent caching and parallel task execution. It’s framework-agnostic and works with any build tool.

Why Turborepo?

Turborepo solves the performance problem that plagues many monorepos. Without optimization, running tasks across hundreds of packages can take hours. Turborepo reduces this to minutes or seconds through:

Intelligent Caching: Cache task outputs based on inputs (files, environment variables, dependencies)
Parallel Execution: Run independent tasks simultaneously
Incremental Builds: Only rebuild what changed
Remote Caching: Share cache across team members and CI/CD

Setting Up Turborepo

Install Turborepo in your monorepo root:

pnpm add -D -w turbo

Create a turbo.json configuration file:

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

Understanding the Pipeline

The pipeline defines tasks that can be run across packages:

dependsOn: Specifies task dependencies

["^build"]: Run build in dependencies first
["build"]: Run build in current package first

outputs: Files/folders to cache (relative to package root)

cache: Whether to cache this task (default: true)

persistent: Whether this task runs continuously (like dev servers)

Running Tasks with Turborepo

Use Turborepo’s CLI to run tasks:

# Run build across all packages
pnpm turbo build

# Run test in specific package
pnpm turbo test --filter=@my-org/web-app

# Run multiple tasks
pnpm turbo build test lint

# Run with specific packages
pnpm turbo build --filter=@my-org/web-app --filter=@my-org/admin-panel

# Skip cache (force rebuild)
pnpm turbo build --force

# Show what would run (dry run)
pnpm turbo build --dry-run

Advanced Turborepo Configuration

Turborepo supports advanced configuration for complex scenarios:

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env"],
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["API_URL"],
      "inputs": ["src/**/*.ts", "package.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": [],
      "outputLogs": "new-only"
    },
    "deploy": {
      "dependsOn": ["build", "test"],
      "outputs": []
    }
  }
}

globalDependencies: Files that affect all packages (like .env)

globalEnv: Environment variables that invalidate cache

env: Environment variables specific to this task

inputs: Specific files to watch for cache invalidation

outputLogs: Control log output ("full", "new-only", "none")

Remote Caching

Turborepo supports remote caching to share cache across team members and CI/CD:

# Link to Vercel (free for open source)
pnpm turbo login
pnpm turbo link

# Or use custom remote cache
export TURBO_TOKEN=your-token
export TURBO_TEAM=your-team
pnpm turbo build

Remote caching dramatically speeds up CI/CD pipelines by reusing cache from previous builds.

Turborepo Best Practices

✅ Define Clear Dependencies: Use dependsOn to ensure correct build order

✅ Specify Outputs: Always define outputs for cacheable tasks

✅ Use Filters: Leverage --filter to run tasks on specific packages

✅ Enable Remote Caching: Share cache across team and CI/CD

✅ Profile Builds: Use --profile to identify slow tasks

# Generate build profile
pnpm turbo build --profile=profile.json

# View profile in Chrome
chrome://tracing

Nx: Enterprise-Grade Monorepo Tools

Nx is a powerful set of extensible dev tools for monorepos, providing not just build optimization but also code generation, dependency graph visualization, and advanced developer tooling. Nx is particularly strong for large, enterprise-scale monorepos.

Why Nx?

Nx offers comprehensive tooling beyond build optimization:

Computation Caching: Similar to Turborepo, with advanced features
Code Generation: Generators and plugins for common patterns
Dependency Graph: Visualize and understand your codebase
Affected Commands: Only run tasks for changed packages
Plugin Ecosystem: Rich plugins for React, Next.js, Angular, NestJS, and more

Setting Up Nx

Create a new Nx workspace:

npx create-nx-workspace@latest my-monorepo

Or add Nx to an existing monorepo:

npx nx@latest init

Nx creates an nx.json configuration file:

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["{projectRoot}/dist"]
    },
    "test": {
      "outputs": []
    },
    "lint": {
      "outputs": []
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/**/*.test.ts"
    ]
  },
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "test", "lint"]
      }
    }
  }
}

Project Configuration

Nx uses project.json files (or package.json with Nx targets) to define project tasks:

{
  "name": "web-app",
  "sourceRoot": "apps/web-app/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web-app"
      }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": {
        "buildTarget": "web-app:build"
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": []
    }
  }
}

Running Tasks with Nx

Nx provides powerful commands for running tasks:

# Run task for specific project
nx build web-app

# Run task for all projects
nx run-many --target=build --all

# Run task for affected projects only
nx affected --target=build

# Run task in parallel
nx run-many --target=test --all --parallel=3

# Graph visualization
nx graph

Nx Plugins and Generators

Nx plugins provide code generators and executors:

# Install React plugin
pnpm add -D @nx/react

# Generate React application
nx generate @nx/react:application my-app

# Generate React library
nx generate @nx/react:library shared-ui

# Generate component
nx generate @nx/react:component button --project=shared-ui

Dependency Graph

Nx’s dependency graph helps visualize your monorepo:

# Open interactive graph
nx graph

# Generate static graph
nx graph --file=graph.html

The graph shows:

Package dependencies
Task dependencies
Affected projects
Build order

Affected Commands

Nx’s affected commands only run tasks for packages that changed:

# Build affected packages
nx affected --target=build

# Test affected packages
nx affected --target=test

# Compare against specific base
nx affected --target=build --base=main --head=HEAD

This dramatically speeds up CI/CD by only testing and building what changed.

Nx Cloud

Nx Cloud provides remote caching and distributed task execution:

# Connect to Nx Cloud
nx connect

# Run with remote cache
nx build --all

Nx Cloud also provides:

Distributed Task Execution: Run tasks across multiple machines
Analytics: Insights into build performance
CI Optimization: Automatic parallelization and caching

Build Optimization Strategies

Optimizing builds in a monorepo requires understanding dependencies, leveraging caching, and parallelizing work. Here are key strategies used by Turborepo, Nx, and other monorepo tools.

Task Dependency Graph

Understanding task dependencies is crucial for optimization. Tasks should run in the correct order:

Package A (no dependencies)
  └─> Package B (depends on A)
      └─> Package C (depends on B)

With proper dependency configuration, Package A builds first, then B, then C. Independent packages can build in parallel.

Incremental Builds

Only rebuild what changed. Tools detect changes through:

File Hashing: Hash input files and compare to cache
Dependency Tracking: Track which files each package depends on
Change Detection: Use Git to determine what changed

{
  "pipeline": {
    "build": {
      "inputs": ["src/**/*.ts", "package.json"],
      "outputs": ["dist/**"]
    }
  }
}

Parallel Execution

Run independent tasks simultaneously:

# Turborepo automatically parallelizes
pnpm turbo build

# Nx with parallel limit
nx run-many --target=build --all --parallel=5

Limit parallelism to avoid overwhelming your machine:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    }
  },
  "remoteCache": {
    "enabled": true
  }
}

Caching Strategies

Effective caching requires:

1. Correct Outputs: Specify all build outputs

{
  "build": {
    "outputs": ["dist/**", ".next/**", "build/**"]
  }
}

2. Environment Variables: Include variables that affect builds

{
  "build": {
    "env": ["NODE_ENV", "API_URL"]
  }
}

3. Input Files: Specify files that affect the build

{
  "build": {
    "inputs": ["src/**/*.ts", "tsconfig.json"]
  }
}

Remote Caching

Share cache across team and CI/CD:

Turborepo: Vercel remote cache or custom implementation
Nx: Nx Cloud or custom cache server
Custom: Implement cache server using Redis or similar

Benefits:

CI/CD builds reuse cache from previous runs
Team members share build artifacts
Faster onboarding for new developers

Build Profiling

Identify bottlenecks:

# Turborepo profiling
pnpm turbo build --profile=profile.json

# Nx timing
nx build --all --verbose

Use profiles to:

Identify slow packages
Optimize task dependencies
Adjust parallelism
Find unnecessary work

Dependency Management in Monorepos

Managing dependencies across multiple packages requires careful strategy to avoid version conflicts, reduce duplication, and maintain consistency.

Hoisting Strategy

pnpm uses a unique hoisting strategy that reduces disk usage while maintaining strict dependency resolution:

node_modules/
├── .pnpm/
│   ├── react@18.2.0/
│   ├── react@19.0.0/
│   └── ...
├── react -> .pnpm/react@18.2.0/node_modules/react
└── ...

Each package gets exactly the versions it needs, but packages are stored once on disk.

Version Consistency

Maintain consistent versions across packages:

// Root package.json
{
  "pnpm": {
    "overrides": {
      "react": "^18.2.0",
      "react-dom": "^18.2.0"
    }
  }
}

Or use pnpm’s peerDependencyRules:

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "18"
      }
    }
  }
}

Internal Package Versions

Use consistent versioning for internal packages:

{
  "name": "@my-org/shared-utils",
  "version": "1.2.3"
}

Consider using a tool like changesets or release-please for version management.

Dependency Updates

Update dependencies efficiently:

# Update all dependencies
pnpm update --recursive

# Update specific dependency
pnpm update react --recursive --latest

# Check for outdated packages
pnpm outdated --recursive

Circular Dependencies

Avoid circular dependencies between packages:

# Detect circular dependencies
pnpm list --depth=10 | grep "circular"

# Use dependency graph visualization
nx graph  # or turbo graph

If circular dependencies exist, extract shared code to a common package.

Task Orchestration and Caching

Effective task orchestration ensures tasks run in the correct order, leverage caching, and execute efficiently.

Task Dependencies

Define clear task dependencies:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"] // Dependencies first
    },
    "test": {
      "dependsOn": ["build"] // Build first
    },
    "deploy": {
      "dependsOn": ["build", "test"] // Both must succeed
    }
  }
}

Cache Keys

Cache keys determine cache hits/misses. Include:

Input files: Source files, config files
Environment variables: NODE_ENV, API_URL, etc.
Dependencies: Package versions, lock file
Task configuration: Build flags, options

{
  "build": {
    "inputs": ["src/**/*.ts", "package.json", "tsconfig.json"],
    "env": ["NODE_ENV"],
    "outputs": ["dist/**"]
  }
}

Cache Invalidation

Invalidate cache when:

Source files change
Dependencies change
Environment variables change
Build configuration changes

Tools automatically detect these changes and invalidate cache.

Task Filtering

Run tasks on specific packages:

# Turborepo
pnpm turbo build --filter=@my-org/web-app

# Nx
nx build web-app

# pnpm
pnpm --filter @my-org/web-app build

Use filters to:

Test specific packages during development
Build only what’s needed
Run tasks in CI/CD for changed packages

Watch Mode

Watch mode rebuilds on file changes:

# Turborepo (via package scripts)
pnpm turbo dev

# Nx
nx serve web-app --watch

Watch mode typically disables caching for real-time feedback.

One of the main benefits of monorepos is easy code sharing through internal packages.

Creating Internal Packages

Create a new package:

# Create package directory
mkdir -p packages/shared-utils
cd packages/shared-utils

# Initialize package
pnpm init

# Create package.json

{
  "name": "@my-org/shared-utils",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  }
}

Using Internal Packages

Reference internal packages using workspace protocol:

{
  "dependencies": {
    "@my-org/shared-utils": "workspace:*",
    "@my-org/ui-components": "workspace:*"
  }
}

After pnpm install, packages are linked automatically.

TypeScript Path Mapping

Configure TypeScript to resolve internal packages:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@my-org/shared-utils": ["packages/shared-utils/src"],
      "@my-org/shared-utils/*": ["packages/shared-utils/src/*"]
    }
  }
}

Building Internal Packages

Build internal packages before consuming packages:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"] // Build dependencies first
    }
  }
}

This ensures shared packages are built before apps that use them.

Publishing Internal Packages

When publishing, replace workspace:* with actual versions:

# pnpm automatically handles this
pnpm publish --filter @my-org/shared-utils

# Or use changesets
pnpm changeset
pnpm changeset version
pnpm changeset publish

Testing Strategies in Monorepos

Testing in monorepos requires strategies for unit tests, integration tests, and end-to-end tests across multiple packages.

Unit Testing

Each package should have its own unit tests:

{
  "scripts": {
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

Run tests across packages:

# Turborepo
pnpm turbo test

# Nx
nx run-many --target=test --all

# pnpm
pnpm --filter './packages/*' test

Integration Testing

Test packages together:

# Test package and its dependencies
pnpm turbo test --filter=@my-org/web-app...

The ... syntax includes the package and all its dependencies.

End-to-End Testing

E2E tests typically live in apps, not packages:

{
  "scripts": {
    "test:e2e": "playwright test"
  }
}

Test Caching

Cache test results:

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "cache": true
    }
  }
}

Tests only run when:

Source files change
Dependencies change
Test configuration changes

Test Coverage

Generate and aggregate coverage:

{
  "test": {
    "outputs": ["coverage/**"]
  }
}

Use tools like nyc or vitest with coverage reporting.

Common Pitfalls and Anti-Patterns

Avoid these common mistakes when working with monorepos.

❌ Circular Dependencies

Problem: Package A depends on B, B depends on A.

Solution: Extract shared code to a third package, or restructure dependencies.

# Detect circular dependencies
pnpm list --depth=10

❌ Incorrect Task Dependencies

Problem: Tasks run in wrong order, causing build failures.

Solution: Define clear dependsOn relationships:

{
  "build": {
    "dependsOn": ["^build"] // Dependencies first
  }
}

❌ Missing Cache Outputs

Problem: Cache doesn’t work because outputs aren’t specified.

Solution: Always specify outputs:

{
  "build": {
    "outputs": ["dist/**", "build/**"]
  }
}

❌ Over-hoisting Dependencies

Problem: Using pnpm’s shamefully-hoist defeats the purpose of strict resolution.

Solution: Use workspace protocol and proper dependency management instead.

❌ Ignoring Affected Packages

Problem: Building/testing everything, even when only one package changed.

Solution: Use affected commands:

# Turborepo
pnpm turbo build --filter='[HEAD^1]'

# Nx
nx affected --target=build

❌ Inconsistent Versions

Problem: Different packages use different versions of the same dependency.

Solution: Use pnpm overrides or peer dependency rules:

{
  "pnpm": {
    "overrides": {
      "react": "^18.2.0"
    }
  }
}

❌ Large Repository Size

Problem: Repository becomes too large, slow to clone.

Solution:

Use Git LFS for large files
Consider splitting into multiple monorepos
Use sparse checkouts
Clean up history periodically

Best Practices

Follow these best practices for maintainable, performant monorepos.

✅ Start Simple

Begin with pnpm workspaces, add Turborepo or Nx when you need optimization:

Set up pnpm workspaces
Organize packages
Add build tooling when needed
Optimize with caching

✅ Consistent Structure

Use a consistent directory structure:

monorepo/
├── apps/          # Applications
├── packages/      # Shared packages
├── tools/         # Tooling packages
└── docs/          # Documentation

✅ Clear Naming Conventions

Use consistent naming:

Packages: @org/package-name
Apps: @org/app-name or just app-name
Tools: @org/tool-name or tool-name

✅ Document Dependencies

Document why packages depend on each other:

/**
 * @package @my-org/web-app
 *
 * This package depends on @my-org/ui-components for shared UI elements
 * and @my-org/shared-utils for utility functions.
 */

✅ Use TypeScript

TypeScript provides better IDE support and catches errors early:

{
  "compilerOptions": {
    "composite": true,
    "baseUrl": ".",
    "paths": {
      "@my-org/*": ["packages/*/src"]
    }
  }
}

✅ Automate Everything

Automate common tasks:

{
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "test": "turbo test",
    "lint": "turbo lint",
    "type-check": "turbo type-check"
  }
}

✅ CI/CD Optimization

Optimize CI/CD pipelines:

- name: Build affected
  run: pnpm turbo build --filter='[HEAD^1]'

- name: Test affected
  run: pnpm turbo test --filter='[HEAD^1]'

✅ Monitor Performance

Track build times and optimize:

# Profile builds
pnpm turbo build --profile

# Check cache hit rates
pnpm turbo build --summarize

✅ Version Management

Use tools for version management:

changesets: Popular, flexible
release-please: Automated releases
lerna: Legacy but still used

✅ Code Ownership

Define code ownership:

# CODEOWNERS
packages/ui-components/ @ui-team
apps/web-app/ @web-team
apps/admin-panel/ @admin-team

Conclusion

Monorepos have become essential for managing large-scale JavaScript and TypeScript projects. Tools like pnpm workspaces, Turborepo, and Nx have made monorepos practical by solving performance and complexity challenges.

Key Takeaways:

pnpm workspaces provide efficient dependency management and workspace features
Turborepo offers high-performance builds through intelligent caching and parallelization
Nx provides comprehensive tooling for enterprise-scale monorepos
Build optimization through caching, incremental builds, and parallel execution is crucial
Proper dependency management prevents version conflicts and reduces duplication
Clear task orchestration ensures correct build order and efficient execution

Start with pnpm workspaces for basic monorepo needs, then add Turborepo or Nx when you need build optimization. Focus on clear structure, consistent tooling, and proper dependency management. As your monorepo grows, leverage affected commands, remote caching, and profiling to maintain performance.

For more on related topics, check out our guides on package manager comparison, micro-frontends architecture, and clean architecture principles.

Whether you’re managing a small monorepo with a few packages or scaling to hundreds, these tools and practices will help you maintain a fast, maintainable, and developer-friendly codebase.

Table of Contents

Introduction

What is a Monorepo?

Core Characteristics

Real-World Examples

Benefits of Monorepos

Challenges of Monorepos

Monorepo vs Multi-repo: When to Use Each

When to Use a Monorepo

When to Use Multi-repo

Hybrid Approach

pnpm Workspaces: Foundation of Modern Monorepos

Setting Up pnpm Workspaces

Root package.json Configuration

Package Configuration

Installing Dependencies

Running Scripts Across Workspaces

Workspace Protocol Benefits

Turborepo: High-Performance Build System

Why Turborepo?

Setting Up Turborepo

Understanding the Pipeline

Running Tasks with Turborepo

Advanced Turborepo Configuration

Remote Caching

Turborepo Best Practices

Nx: Enterprise-Grade Monorepo Tools

Why Nx?

Setting Up Nx

Project Configuration

Running Tasks with Nx

Nx Plugins and Generators

Dependency Graph

Affected Commands

Nx Cloud

Build Optimization Strategies

Task Dependency Graph

Incremental Builds

Parallel Execution

Caching Strategies

Remote Caching

Build Profiling

Dependency Management in Monorepos

Hoisting Strategy

Version Consistency

Internal Package Versions

Dependency Updates

Circular Dependencies

Task Orchestration and Caching

Task Dependencies

Cache Keys

Cache Invalidation

Task Filtering

Watch Mode

Code Sharing and Internal Packages

Creating Internal Packages

Using Internal Packages

TypeScript Path Mapping

Building Internal Packages

Publishing Internal Packages

Testing Strategies in Monorepos

Unit Testing

Integration Testing

End-to-End Testing

Test Caching

Test Coverage

Common Pitfalls and Anti-Patterns

❌ Circular Dependencies

❌ Incorrect Task Dependencies

❌ Missing Cache Outputs

❌ Over-hoisting Dependencies

❌ Ignoring Affected Packages

❌ Inconsistent Versions

❌ Large Repository Size

Best Practices

✅ Start Simple

✅ Consistent Structure

✅ Clear Naming Conventions

✅ Document Dependencies

✅ Use TypeScript