Monorepo Management

Build efficient, scalable monorepos that enable code sharing, consistent tooling, and atomic changes across multiple packages and applications.

When to Use This Skill

• Setting up new monorepo projects

• Migrating from multi-repo to monorepo

• Optimizing build and test performance

• Managing shared dependencies

• Implementing code sharing strategies

• Setting up CI/CD for monorepos

• Versioning and publishing packages

• Debugging monorepo-specific issues

Core Concepts

1. Why Monorepos?

Advantages:

• Shared code and dependencies

• Atomic commits across projects

• Consistent tooling and standards

• Easier refactoring

• Simplified dependency management

• Better code visibility

Challenges:

• Build performance at scale

• CI/CD complexity

• Access control

• Large Git repository

2. Monorepo Tools

Package Managers:

• pnpm workspaces (recommended)

• npm workspaces

• Yarn workspaces

Build Systems:

• Turborepo (recommended for most)

• Nx (feature-rich, complex)

• Lerna (older, maintenance mode)

Turborepo Setup

Initial Setup

# Create new monorepo

npx create-turbo@latest my-monorepo

cd my-monorepo

# Structure:

# apps/

#   web/          - Next.js app

#   docs/         - Documentation site

# packages/

#   ui/           - Shared UI components

#   config/       - Shared configurations

#   tsconfig/     - Shared TypeScript configs

# turbo.json      - Turborepo configuration

# package.json    - Root package.json

Configuration

// turbo.json

{

  "$schema": "https://turbo.build/schema.json",

  "globalDependencies": ["**/.env.*local"],

  "pipeline": {

    "build": {

      "dependsOn": ["^build"],

      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]

    },

    "test": {

      "dependsOn": ["build"],

      "outputs": ["coverage/**"]

    },

    "lint": {

      "outputs": []

    },

    "dev": {

      "cache": false,

      "persistent": true

    },

    "type-check": {

      "dependsOn": ["^build"],

      "outputs": []

    }

  }

}

// package.json (root)

{

  "name": "my-monorepo",

  "private": true,

  "workspaces": ["apps/*", "packages/*"],

  "scripts": {

    "build": "turbo run build",

    "dev": "turbo run dev",

    "test": "turbo run test",

    "lint": "turbo run lint",

    "format": "prettier --write \"**/*.{ts,tsx,md}\"",

    "clean": "turbo run clean && rm -rf node_modules"

  },

  "devDependencies": {

    "turbo": "^1.10.0",

    "prettier": "^3.0.0",

    "typescript": "^5.0.0"

  },

  "packageManager": "pnpm@8.0.0"

}

Package Structure

// packages/ui/package.json

{

  "name": "@repo/ui",

  "version": "0.0.0",

  "private": true,

  "main": "./dist/index.js",

  "types": "./dist/index.d.ts",

  "exports": {

    ".": {

      "import": "./dist/index.js",

      "types": "./dist/index.d.ts"

    },

    "./button": {

      "import": "./dist/button.js",

      "types": "./dist/button.d.ts"

    }

  },

  "scripts": {

    "build": "tsup src/index.ts --format esm,cjs --dts",

    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",

    "lint": "eslint src/",

    "type-check": "tsc --noEmit"

  },

  "devDependencies": {

    "@repo/tsconfig": "workspace:*",

    "tsup": "^7.0.0",

    "typescript": "^5.0.0"

  },

  "dependencies": {

    "react": "^18.2.0"

  }

}

pnpm Workspaces

Setup

# pnpm-workspace.yaml

packages:

  - "apps/*"

  - "packages/*"

  - "tools/*"

// .npmrc

# Hoist shared dependencies

shamefully-hoist=true

# Strict peer dependencies

auto-install-peers=true

strict-peer-dependencies=true

# Performance

store-dir=~/.pnpm-store

Dependency Management

# Install dependency in specific package

pnpm add react --filter @repo/ui

pnpm add -D typescript --filter @repo/ui

# Install workspace dependency

pnpm add @repo/ui --filter web

# Install in all packages

pnpm add -D eslint -w

# Update all dependencies

pnpm update -r

# Remove dependency

pnpm remove react --filter @repo/ui

Scripts

# Run script in specific package

pnpm --filter web dev

pnpm --filter @repo/ui build

# Run in all packages

pnpm -r build

pnpm -r test

# Run in parallel

pnpm -r --parallel dev

# Filter by pattern

pnpm --filter "@repo/*" build

pnpm --filter "...web" build  # Build web and dependencies

Nx Monorepo

Setup

# Create Nx monorepo

npx create-nx-workspace@latest my-org

# Generate applications

nx generate @nx/react:app my-app

nx generate @nx/next:app my-next-app

# Generate libraries

nx generate @nx/react:lib ui-components

nx generate @nx/js:lib utils

Configuration

// nx.json

{

  "extends": "nx/presets/npm.json",

  "$schema": "./node_modules/nx/schemas/nx-schema.json",

  "targetDefaults": {

    "build": {

      "dependsOn": ["^build"],

      "inputs": ["production", "^production"],

      "cache": true

    },

    "test": {

      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],

      "cache": true

    },

    "lint": {

      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],

      "cache": true

    }

  },

  "namedInputs": {

    "default": ["{projectRoot}/**/*", "sharedGlobals"],

    "production": [

      "default",

      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",

      "!{projectRoot}/tsconfig.spec.json"

    ],

    "sharedGlobals": []

  }

}

Running Tasks

# Run task for specific project

nx build my-app

nx test ui-components

nx lint utils

# Run for affected projects

nx affected:build

nx affected:test --base=main

# Visualize dependencies

nx graph

# Run in parallel

nx run-many --target=build --all --parallel=3

Shared Configurations

TypeScript Configuration

// packages/tsconfig/base.json

{

  "compilerOptions": {

    "strict": true,

    "esModuleInterop": true,

    "skipLibCheck": true,

    "forceConsistentCasingInFileNames": true,

    "module": "ESNext",

    "moduleResolution": "bundler",

    "resolveJsonModule": true,

    "isolatedModules": true,

    "incremental": true,

    "declaration": true

  },

  "exclude": ["node_modules"]

}

// packages/tsconfig/react.json

{

  "extends": "./base.json",

  "compilerOptions": {

    "jsx": "react-jsx",

    "lib": ["ES2022", "DOM", "DOM.Iterable"]

  }

}

// apps/web/tsconfig.json

{

  "extends": "@repo/tsconfig/react.json",

  "compilerOptions": {

    "outDir": "dist",

    "rootDir": "src"

  },

  "include": ["src"],

  "exclude": ["node_modules", "dist"]

}

ESLint Configuration

// packages/config/eslint-preset.js

module.exports = {

  extends: [

    "eslint:recommended",

    "plugin:@typescript-eslint/recommended",

    "plugin:react/recommended",

    "plugin:react-hooks/recommended",

    "prettier",

  ],

  plugins: ["@typescript-eslint", "react", "react-hooks"],

  parser: "@typescript-eslint/parser",

  parserOptions: {

    ecmaVersion: 2022,

    sourceType: "module",

    ecmaFeatures: {

      jsx: true,

    },

  },

  settings: {

    react: {

      version: "detect",

    },

  },

  rules: {

    "@typescript-eslint/no-unused-vars": "error",

    "react/react-in-jsx-scope": "off",

  },

};

// apps/web/.eslintrc.js

module.exports = {

  extends: ["@repo/config/eslint-preset"],

  rules: {

    // App-specific rules

  },

};

Code Sharing Patterns

Pattern 1: Shared UI Components

// packages/ui/src/button.tsx

import * as React from 'react';

export interface ButtonProps {

  variant?: 'primary' | 'secondary';

  children: React.ReactNode;

  onClick?: () => void;

}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {

  return (

    <button

      className={`btn btn-${variant}`}

      onClick={onClick}

    >

      {children}

    </button>

  );

}

// packages/ui/src/index.ts

export { Button, type ButtonProps } from './button';

export { Input, type InputProps } from './input';

// apps/web/src/app.tsx

import { Button } from '@repo/ui';

export function App() {

  return <Button variant="primary">Click me</Button>;

}

Pattern 2: Shared Utilities

// packages/utils/src/string.ts

export function capitalize(str: string): string {

  return str.charAt(0).toUpperCase() + str.slice(1);

}

export function truncate(str: string, length: number): string {

  return str.length > length ? str.slice(0, length) + "..." : str;

}

// packages/utils/src/index.ts

export * from "./string";

export * from "./array";

export * from "./date";

// Usage in apps

import { capitalize, truncate } from "@repo/utils";

Pattern 3: Shared Types

// packages/types/src/user.ts

export interface User {

  id: string;

  email: string;

  name: string;

  role: "admin" | "user";

}

export interface CreateUserInput {

  email: string;

  name: string;

  password: string;

}

// Used in both frontend and backend

import type { User, CreateUserInput } from "@repo/types";

Build Optimization

Turborepo Caching

// turbo.json

{

  "pipeline": {

    "build": {

      // Build depends on dependencies being built first

      "dependsOn": ["^build"],

      // Cache these outputs

      "outputs": ["dist/**", ".next/**"],

      // Cache based on these inputs (default: all files)

      "inputs": ["src/**/*.tsx", "src/**/*.ts", "package.json"]

    },

    "test": {

      // Run tests in parallel, don't depend on build

      "cache": true,

      "outputs": ["coverage/**"]

    }

  }

}

Remote Caching

# Turborepo Remote Cache (Vercel)

npx turbo login

npx turbo link

# Custom remote cache

# turbo.json

{

  "remoteCache": {

    "signature": true,

    "enabled": true

  }

}

CI/CD for Monorepos

GitHub Actions

# .github/workflows/ci.yml

name: CI

on:

  push:

    branches: [main]

  pull_request:

    branches: [main]

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v3

        with:

          fetch-depth: 0 # For Nx affected commands

      - uses: pnpm/action-setup@v2

        with:

          version: 8

      - uses: actions/setup-node@v3

        with:

          node-version: 18

          cache: "pnpm"

      - name: Install dependencies

        run: pnpm install --frozen-lockfile

      - name: Build

        run: pnpm turbo run build

      - name: Test

        run: pnpm turbo run test

      - name: Lint

        run: pnpm turbo run lint

      - name: Type check

        run: pnpm turbo run type-check

Deploy Affected Only

# Deploy only changed apps

- name: Deploy affected apps

  run: |

    if pnpm nx affected:apps --base=origin/main --head=HEAD | grep -q "web"; then

      echo "Deploying web app"

      pnpm --filter web deploy

    fi

Best Practices

• Consistent Versioning: Lock dependency versions across workspace

• Shared Configs: Centralize ESLint, TypeScript, Prettier configs

• Dependency Graph: Keep it acyclic, avoid circular dependencies

• Cache Effectively: Configure inputs/outputs correctly

• Type Safety: Share types between frontend/backend

• Testing Strategy: Unit tests in packages, E2E in apps

• Documentation: README in each package

• Release Strategy: Use changesets for versioning

Common Pitfalls

• Circular Dependencies: A depends on B, B depends on A

• Phantom Dependencies: Using deps not in package.json

• Incorrect Cache Inputs: Missing files in Turborepo inputs

• Over-Sharing: Sharing code that should be separate

• Under-Sharing: Duplicating code across packages

• Large Monorepos: Without proper tooling, builds slow down

Publishing Packages

# Using Changesets

pnpm add -Dw @changesets/cli

pnpm changeset init

# Create changeset

pnpm changeset

# Version packages

pnpm changeset version

# Publish

pnpm changeset publish

# .github/workflows/release.yml

- name: Create Release Pull Request or Publish

  uses: changesets/action@v1

  with:

    publish: pnpm release

  env:

    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}