monorepo-architecture

What this skill does

# Monorepo Architecture Skill

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

```text
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.

```text
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.

```text
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.

```json
{
  "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.

```json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": {
    "packages": [
      "apps/*",
      "packages/*"
    ],
    "nohoist": [
      "**/react-native",
      "**/react-native/**"
    ]
  },
  "packageManager": "[email protected]"
}
```

With `.yarnrc.yml` for Yarn Berry:

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

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

With workspace-specific `.npmrc`:

```ini
# .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.

```toml
# 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:

```toml
# 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.

```json
{
  "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.

```json
{
  "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 Synchroni