monorepo-management

• 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

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)

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"

}

}

```

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

```

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

```

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

},

};

```

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 (

className={btn btn-${variant}}

onClick={onClick}

>

{children}

);

}

// 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 Click me;

}

```

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';

```

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

}

}

```

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

```

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

• 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

```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 }}

```

• 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