monorepo-management

upstream

Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependency management. Use when setting up monorepos, optimizing builds, or managing shared dependencies.

ID: monorepo-management

Volver

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

``bash


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

`json


// 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": []
    }
  }
}

`json


// 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

`json


// 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

`yaml


pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - 'tools/*'

`json


// .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

`bash


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

`bash


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

`bash


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

`json


// 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

`bash


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

`json


// 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

`javascript


// 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

`typescript


// 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

`typescript


// 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

`typescript


// 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

`json


// 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
`bash
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
`yaml
.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
`yaml
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

1. Consistent Versioning: Lock dependency versions across workspace

2. Shared Configs: Centralize ESLint, TypeScript, Prettier configs

3. Dependency Graph: Keep it acyclic, avoid circular dependencies

4. Cache Effectively: Configure inputs/outputs correctly

5. Type Safety: Share types between frontend/backend

6. Testing Strategy: Unit tests in packages, E2E in apps

7. Documentation: README in each package

8. 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

`bash
Using Changesets pnpm add -Dw @changesets/cli pnpm changeset init Create changeset pnpm changeset Version packages pnpm changeset version Publish pnpm changeset publish
`
`yaml
.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 }}
``

Resources

references/turborepo-guide.md: Comprehensive Turborepo documentation

references/nx-guide.md: Nx monorepo patterns

references/pnpm-workspaces.md: pnpm workspace features

assets/monorepo-checklist.md: Setup checklist

assets/migration-guide.md: Multi-repo to monorepo migration

scripts/dependency-graph.ts**: Visualize package dependencies

Informacion

Estado	Activo
Origen	upstream
Usos	3
Ultimo uso	23/01 16:57
Actualizado	09/01/2026 02:14

Archivo origen

Z:\Repositorios\core\upstream\plugins\developer-essentials\skills\monorepo-management\SKILL.md