Documentation/Jutsu/Monorepo/ skills /monorepo-architecture

📖 monorepo-architecture

Use when designing monorepo structure, organizing packages, or migrating to monorepo architecture with architectural patterns for managing dependencies and scalable workspace configurations.

Overview

This skill provides comprehensive guidance on designing and structuring monorepos, including workspace organization, dependency management, versioning strategies, and architectural patterns that scale from small projects to enterprise applications.

Monorepo vs Polyrepo

When to Choose Monorepo

A monorepo is beneficial when:

Code sharing is frequent: Multiple projects share common libraries, utilities, or components
Atomic changes needed: Changes span multiple packages and need to be deployed together
Unified tooling: All projects benefit from consistent linting, testing, and build processes
Team collaboration: Teams work across project boundaries and need visibility into related code
Version synchronization: Related packages should maintain version alignment
Refactoring at scale: Large-scale refactoring across projects is common
Single source of truth: All code, documentation, and tooling in one place

When to Choose Polyrepo

A polyrepo is beneficial when:

Independent release cycles: Projects deploy on completely different schedules
Different tech stacks: Projects use incompatible tooling or languages
Access control: Different teams need isolated access to separate codebases
Repository size concerns: Combined codebase would be too large to manage efficiently
External dependencies: Projects are maintained by different organizations
Simple project structure: Overhead of monorepo tooling outweighs benefits

Tradeoffs

Monorepo Advantages:

Simplified dependency management
Easier refactoring across boundaries
Consistent tooling and standards
Better code discoverability
Atomic commits across projects
Single CI/CD pipeline

Monorepo Challenges:

Repository size growth
CI/CD complexity
Build time management
Git performance at scale
Tooling requirements
Learning curve for developers

Repository Structure Patterns

Package-Based Structure

Organize by technical layer or package type.

my-monorepo/
├── apps/
│   ├── web/                 # Next.js web application
│   ├── mobile/              # React Native app
│   └── api/                 # Node.js API server
├── packages/
│   ├── ui/                  # Shared UI components
│   ├── utils/               # Shared utilities
│   ├── config/              # Shared configurations
│   └── types/               # Shared TypeScript types
├── services/
│   ├── auth/                # Authentication service
│   ├── payments/            # Payment processing
│   └── notifications/       # Notification service
└── tooling/
    ├── eslint-config/       # ESLint configuration
    └── tsconfig/            # TypeScript configuration

Best for: Technical separation, shared library focus, platform diversity.

Domain-Based Structure

Organize by business domain or feature.

my-monorepo/
├── domains/
│   ├── user/
│   │   ├── api/            # User API
│   │   ├── web/            # User web UI
│   │   ├── mobile/         # User mobile UI
│   │   └── shared/         # User shared code
│   ├── billing/
│   │   ├── api/
│   │   ├── web/
│   │   └── shared/
│   └── analytics/
│       ├── api/
│       ├── web/
│       └── shared/
└── shared/
    ├── ui/                 # Cross-domain UI components
    ├── utils/              # Cross-domain utilities
    └── config/             # Cross-domain config

Best for: Domain-driven design, team ownership by feature, microservices architecture.

Hybrid Structure

Combine package-based and domain-based approaches.

my-monorepo/
├── apps/
│   ├── customer-portal/    # Customer-facing app
│   └── admin-dashboard/    # Admin app
├── features/
│   ├── auth/               # Authentication feature
│   ├── checkout/           # Checkout feature
│   └── inventory/          # Inventory feature
├── packages/
│   ├── ui/                 # Shared UI library
│   ├── api-client/         # API client library
│   └── analytics/          # Analytics library
└── infrastructure/
    ├── database/           # Database utilities
    ├── messaging/          # Message queue
    └── deployment/         # Deployment configs

Best for: Complex organizations, balancing technical and domain concerns.

Workspace Configuration

NPM Workspaces

Basic workspace setup using native NPM workspaces.

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "dev": "npm run dev --workspaces",
    "build": "npm run build --workspaces",
    "test": "npm run test --workspaces"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "eslint": "^8.54.0"
  }
}

Key Features:

Native NPM support (v7+)
Simple configuration
Automatic workspace linking
Shared dependency hoisting
Workspace-specific commands

Yarn Workspaces

Yarn's workspace implementation with additional features.

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": {
    "packages": [
      "apps/*",
      "packages/*"
    ],
    "nohoist": [
      "**/react-native",
      "**/react-native/**"
    ]
  },
  "packageManager": "yarn@3.6.4"
}

With .yarnrc.yml for Yarn Berry:

nodeLinker: node-modules

plugins:
  - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
    spec: "@yarnpkg/plugin-workspace-tools"

enableGlobalCache: true

compressionLevel: mixed

Key Features:

Fast installation
Plugin system (Yarn Berry)
Advanced workspace commands
No-hoist for specific dependencies
Zero-installs capability

PNPM Workspaces

PNPM's efficient workspace implementation.

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - 'services/*'
  - '!**/test/**'

With workspace-specific .npmrc:

# .npmrc
shared-workspace-lockfile=true
link-workspace-packages=true
prefer-workspace-packages=true
strict-peer-dependencies=false
auto-install-peers=true

Key Features:

Content-addressable storage
Strict node_modules structure
Faster than NPM/Yarn
Efficient disk space usage
Built-in monorepo support

Cargo Workspaces (Rust)

Rust monorepo workspace configuration.

# Cargo.toml (root)
[workspace]
members = [
    "crates/core",
    "crates/api",
    "crates/cli",
]
exclude = ["archived/*"]

[workspace.package]
version = "1.0.0"
edition = "2021"
license = "MIT"

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.35", features = ["full"] }

Individual crate:

# crates/core/Cargo.toml
[package]
name = "my-core"
version.workspace = true
edition.workspace = true
license.workspace = true

[dependencies]
serde.workspace = true
tokio.workspace = true
my-api = { path = "../api" }

Dependency Management

Internal Package Dependencies

Specify dependencies on other workspace packages.

{
  "name": "@myorg/web-app",
  "version": "1.0.0",
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:^",
    "@myorg/api-client": "1.2.3",
    "react": "^18.2.0"
  }
}

Workspace Protocol Variants:

workspace:* - Any version in workspace
workspace:^ - Compatible version (semver caret)
workspace:~ - Patch-level version (semver tilde)
Specific version - Exact workspace version

Shared Dependencies Hoisting

Configure how dependencies are hoisted to root.

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "nohoist": [
      "**/react-native",
      "**/react-native/**",
      "**/@babel/**"
    ]
  }
}

Hoisting Strategies:

Full hoisting: All common dependencies at root (default)
Selective hoisting: Specific packages hoisted, others isolated
No hoisting: Each package has isolated dependencies
Public hoisting: Only public dependencies hoisted

Version Synchronization

Keep related dependencies in sync across packages.

{
  "name": "my-monorepo",
  "private": true,
  "syncpack": {
    "semverGroups": [
      {
        "range": "",
        "dependencies": ["react", "react-dom"],
        "packages": ["**"]
      }
    ],
    "versionGroups": [
      {
        "label": "React ecosystem must match",
        "dependencies": ["react", "react-dom"],
        "dependencyTypes": ["prod", "dev"],
        "pinVersion": "18.2.0"
      }
    ]
  }
}

Use tools like syncpack to enforce consistency:

# Check for version inconsistencies
pnpm syncpack list-mismatches

# Fix version inconsistencies
pnpm syncpack fix-mismatches

# Update all versions
pnpm syncpack update

Peer Dependencies in Monorepos

Handle peer dependencies correctly across workspace packages.

{
  "name": "@myorg/ui",
  "version": "1.0.0",
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "peerDependenciesMeta": {
    "react-dom": {
      "optional": true
    }
  },
  "devDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

Best Practices:

Declare peer dependencies in shared libraries
Include peer deps as dev dependencies for testing
Use peerDependenciesMeta for optional peers
Document peer dependency requirements
Test with minimum and maximum peer versions

Code Organization

Shared Code Patterns

Organize shared code for maximum reusability.

packages/
├── ui/
│   ├── src/
│   │   ├── components/      # Reusable components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── styles/          # Shared styles
│   │   └── index.ts         # Public API
│   └── package.json
├── utils/
│   ├── src/
│   │   ├── string/          # String utilities
│   │   ├── date/            # Date utilities
│   │   ├── validation/      # Validation functions
│   │   └── index.ts         # Public API
│   └── package.json
└── config/
    ├── eslint-config/
    ├── tsconfig/
    └── prettier-config/

Shared Library Design:

Clear public API via barrel exports
Minimal external dependencies
Well-documented interfaces
Comprehensive unit tests
Semantic versioning
Changelog maintenance

Type Sharing Across Packages

Share TypeScript types efficiently.

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: UserRole;
}

export enum UserRole {
  Admin = 'admin',
  User = 'user',
  Guest = 'guest',
}

export type CreateUserInput = Omit<User, 'id'>;
export type UpdateUserInput = Partial<CreateUserInput>;

// packages/types/package.json
{
  "name": "@myorg/types",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./user": {
      "types": "./dist/user.d.ts",
      "default": "./dist/user.js"
    }
  }
}

Configuration Sharing

Share build and tooling configuration across packages.

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

// apps/web/tsconfig.json
{
  "extends": "@myorg/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"],
  "references": [
    { "path": "../../packages/ui" },
    { "path": "../../packages/utils" }
  ]
}

Build Dependencies

Dependency Graphs

Understand and visualize package dependencies.

{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/api-client": "workspace:*"
  }
}

Generate dependency graph:

# Using pnpm
pnpm list --depth 10 --json > deps.json

# Using Nx
nx graph

# Using custom script
node scripts/generate-dep-graph.js

Build Order Optimization

Ensure packages build in correct dependency order.

{
  "name": "my-monorepo",
  "scripts": {
    "build": "turbo run build",
    "build:order": "pnpm -r --workspace-concurrency=1 run build"
  }
}

Turbo pipeline configuration:

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    }
  }
}

Dependency Resolution:

^build - Build dependencies first
dependsOn - Explicit task dependencies
Topological sorting for correct order
Parallel execution when safe

Circular Dependency Detection

Prevent and detect circular dependencies.

// scripts/check-circular-deps.js
import madge from 'madge';

async function checkCircularDeps() {
  const result = await madge('src', {
    fileExtensions: ['ts', 'tsx'],
    detectiveOptions: {
      ts: { skipTypeImports: true }
    }
  });

  const circular = result.circular();
  if (circular.length > 0) {
    console.error('Circular dependencies detected:');
    circular.forEach(cycle => {
      console.error(cycle.join(' -> '));
    });
    process.exit(1);
  }
}

checkCircularDeps();

Add to CI pipeline:

# .github/workflows/ci.yml
- name: Check circular dependencies
  run: pnpm check:circular

Versioning Strategies

Independent Versioning

Each package has its own version, released independently.

{
  "name": "@myorg/ui",
  "version": "2.1.0"
}

{
  "name": "@myorg/utils",
  "version": "1.5.3"
}

Advantages:

Fine-grained version control
Independent release cycles
Clear package maturity
Semantic versioning per package

Use when:

Packages have different stability levels
Release frequency varies significantly
Packages serve different purposes

Fixed/Locked Versioning

All packages share the same version number.

{
  "name": "@myorg/ui",
  "version": "3.2.0"
}

{
  "name": "@myorg/utils",
  "version": "3.2.0"
}

Advantages:

Simplified version management
Clear release coordination
Easier to track compatibility
Unified changelog

Use when:

Packages are tightly coupled
All packages release together
Single product with multiple packages
Version sync is critical

Semantic Versioning in Monorepos

Apply semver principles to workspace packages.

Breaking Changes (Major):

Change public API signatures
Remove exported functions
Change function behavior significantly
Update peer dependencies with breaking changes

New Features (Minor):

Add new exports
Add optional parameters
Enhance existing functionality
Add new optional features

Bug Fixes (Patch):

Fix bugs without API changes
Update documentation
Refactor internal implementation
Update dependencies (non-breaking)

Best Practices

1. Clear Package Boundaries

Define explicit boundaries and responsibilities for each package.

Implementation:

Document package purpose and scope
Define public API explicitly
Use barrel exports (index.ts)
Minimize cross-package coupling
Review package boundaries regularly

Example:

// packages/ui/src/index.ts - Clear public API
export { Button } from './components/Button';
export { Input } from './components/Input';
export type { ButtonProps, InputProps } from './types';

// Internal implementation details NOT exported
// ./components/Button/ButtonStyles.ts
// ./utils/internal-helper.ts

2. Minimal Coupling Between Packages

Reduce dependencies between packages to maintain flexibility.

Implementation:

Use dependency injection
Prefer composition over inheritance
Define clear interfaces
Avoid deep dependency chains
Use events/messaging for loose coupling

Example:

// Loose coupling via interfaces
interface Logger {
  log(message: string): void;
}

class PaymentService {
  constructor(private logger: Logger) {}

  processPayment(amount: number) {
    this.logger.log(`Processing payment: ${amount}`);
    // Implementation
  }
}

3. Shared Tooling Configuration

Maintain consistent tooling across all packages.

Implementation:

Create shared config packages
Extend base configurations
Use workspace inheritance
Document configuration decisions
Automate configuration validation

Example:

// packages/eslint-config/index.json
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "no-console": "warn",
    "@typescript-eslint/no-unused-vars": "error"
  }
}

4. Consistent Naming Conventions

Use predictable naming patterns across packages.

Implementation:

Scope all packages (@org/package-name)
Use kebab-case for package names
Prefix related packages consistently
Follow language/ecosystem conventions
Document naming standards

Example:

@myorg/web-app
@myorg/mobile-app
@myorg/ui-components
@myorg/api-client
@myorg/utils-date
@myorg/utils-string
@myorg/config-eslint
@myorg/config-typescript

5. Documentation Standards

Maintain comprehensive documentation for all packages.

Implementation:

README in every package
API documentation
Usage examples
Migration guides
Contribution guidelines

Example:

# @myorg/ui

React component library for MyOrg applications.

## Installation

`pnpm add @myorg/ui`

## Usage

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

<Button onClick={handleClick}>Click me</Button>

## API Reference

See [API.md](./API.md) for detailed documentation.

6. Package Ownership

Assign clear ownership and responsibility for packages.

Implementation:

CODEOWNERS file
Package maintainer documentation
Review process for changes
Communication channels
Ownership rotation plan

Example:

# CODEOWNERS
/packages/ui/ @frontend-team
/packages/api-client/ @api-team
/packages/auth/ @security-team
/services/ @backend-team

7. API Contracts

Define and maintain clear API contracts between packages.

Implementation:

TypeScript interfaces
OpenAPI specifications
JSON Schema
Contract testing
Version compatibility matrix

Example:

// packages/api-client/src/contracts.ts
/**
 * User API contract
 * @version 1.0.0
 */
export interface UserAPI {
  getUser(id: string): Promise<User>;
  createUser(data: CreateUserInput): Promise<User>;
  updateUser(id: string, data: UpdateUserInput): Promise<User>;
  deleteUser(id: string): Promise<void>;
}

8. Migration Strategies

Plan for package updates and breaking changes.

Implementation:

Deprecation warnings
Migration guides
Compatibility layers
Automated migrations (codemods)
Version upgrade paths

Example:

// Deprecation with migration path
/**
 * @deprecated Use `getUser` instead
 * This function will be removed in v3.0.0
 */
export function fetchUser(id: string): Promise<User> {
  console.warn('fetchUser is deprecated, use getUser instead');
  return getUser(id);
}

9. Security Boundaries

Maintain security isolation between packages.

Implementation:

Separate sensitive packages
Access control policies
Security scanning per package
Dependency audit
Secret management

Example:

{
  "scripts": {
    "security:audit": "pnpm audit --audit-level=high",
    "security:check": "pnpm dlx audit-ci --high"
  }
}

10. Testing Isolation

Ensure tests don't have unintended dependencies.

Implementation:

Package-level test configuration
Mock workspace dependencies
Integration test suites
CI test isolation
Test data management

Example:

// packages/ui/src/__tests__/Button.test.tsx
import { render, screen } from '@testing-library/react';
import { Button } from '../Button';

// Test isolated from other packages
describe('Button', () => {
  it('renders correctly', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });
});

Common Pitfalls

1. Tight Coupling Between Packages

Creating excessive dependencies between packages.

Symptoms:

Changes require updates across many packages
Difficult to extract or move packages
Long dependency chains
Circular dependencies

Solution:

Use dependency injection
Define clear interfaces
Implement event-driven communication
Regular refactoring to reduce coupling

2. Unclear Package Responsibilities

Packages with overlapping or undefined purposes.

Symptoms:

Duplicate functionality
Uncertain where to add features
Inconsistent implementations
Code duplication

Solution:

Document package purpose clearly
Single Responsibility Principle
Regular architecture reviews
Refactor to clarify boundaries

3. Inconsistent Dependency Versions

Different versions of same dependency across packages.

Symptoms:

Build errors
Runtime conflicts
Peer dependency warnings
Bundle size bloat

Solution:

Use workspace protocol
Implement syncpack or similar
Centralize version management
CI checks for consistency

4. Poor Build Optimization

Not leveraging caching and incremental builds.

Symptoms:

Slow build times
Rebuilding unchanged packages
Long CI pipeline runs
Developer frustration

Solution:

Implement build caching (Turborepo, Nx)
Use affected analysis
Configure incremental builds
Optimize build pipelines

5. Missing Documentation

Inadequate documentation for packages and APIs.

Symptoms:

Frequent questions about usage
Incorrect usage patterns
Difficult onboarding
Knowledge silos

Solution:

README in every package
API documentation generation
Usage examples
Onboarding guides

6. Monolithic Thinking in Monorepo

Treating monorepo as single large application.

Symptoms:

Shared global state
Tightly coupled code
Difficult to extract packages
No clear package boundaries

Solution:

Design packages as independent units
Minimize shared global state
Clear separation of concerns
Regular boundary reviews

7. Over-Sharing Code

Sharing code that should remain private.

Symptoms:

Implementation details exposed
Brittle dependencies
Difficult to refactor
Version management complexity

Solution:

Use barrel exports for public API
Keep internals private
Document public vs private
Review exports regularly

8. Ignoring Package Boundaries

Importing from package internals instead of public API.

Symptoms:

Brittle imports
Breaking changes on refactor
Unclear dependencies
Type errors

Solution:

Only import from package root
Configure linting rules
Use TypeScript project references
Code review enforcement

9. No Versioning Strategy

Lack of clear versioning approach.

Symptoms:

Unclear compatibility
Breaking changes without warning
Difficult rollbacks
Consumer confusion

Solution:

Choose fixed or independent versioning
Use changesets or conventional commits
Semantic versioning discipline
Automated version management

10. Complex Dependency Chains

Deep or circular dependency relationships.

Symptoms:

Difficult to understand flow
Build order issues
Circular dependency errors
Maintenance difficulty

Solution:

Visualize dependency graph
Refactor to reduce depth
Break circular dependencies
Use dependency injection

When to Use This Skill

Apply monorepo architecture principles when:

Designing new monorepos - Setting up structure and organization
Refactoring existing repos - Improving architecture and organization
Migrating to monorepo - Moving from polyrepo to monorepo
Scaling monorepo - Growing from small to large monorepo
Organizing packages - Deciding package boundaries and structure
Managing dependencies - Handling internal and external dependencies
Establishing patterns - Creating architectural standards
Reviewing architecture - Evaluating existing monorepo structure
Troubleshooting issues - Solving dependency or organization problems
Planning refactors - Restructuring packages or dependencies

Resources

Monorepo.tools - Comprehensive comparison of monorepo tools and patterns
Turborepo Handbook - Best practices for Turborepo architecture
Nx Monorepo Guide - Architectural concepts and patterns
PNPM Workspaces - Documentation for PNPM workspace features
Yarn Workspaces - Yarn workspace implementation guide
Lerna Documentation - Multi-package repository management
Bazel Documentation - Build and test system for large monorepos
Rush Documentation - Scalable monorepo manager for JavaScript