Part 3: Monorepo vs Polyrepo Strategies

Introduction

I'll never forget the frustration of managing shared TypeScript packages across five different microservices stored in separate repositories. Whenever I updated a shared authentication library, I had to:

1. Publish the package to our private npm registry

2. Update package.json in five different repositories

3. Create five separate pull requests

4. Wait for five separate CI/CD pipelines

5. Deploy five services independently

This process took hours and was error-prone. Then I discovered monorepos and everything changed. But monorepos aren't always the answer—I later worked on a project where a monorepo became a nightmare. In this part, I'll share my real-world experience with both approaches and help you choose what's right for your projects.

Understanding Repository Strategies

Before diving into pros and cons, let's define these terms clearly:

Polyrepo (Multiple Repositories)

Each project, service, or library lives in its own repository.

Example Structure:

GitHub Organization: my-company
├── user-service (repo)
├── payment-service (repo)
├── inventory-service (repo)
├── notification-service (repo)
└── shared-lib (repo)

Monorepo (Single Repository)

Multiple projects, services, or libraries live in one repository with a structured directory layout.

Example Structure:

my-company-monorepo (repo)
├── services/
│   ├── user-service/
│   ├── payment-service/
│   ├── inventory-service/
│   └── notification-service/
├── packages/
│   ├── shared-types/
│   ├── auth-lib/
│   └── database-lib/
└── infrastructure/
    └── terraform/

Polyrepo: My First Approach

When I started building a multi-tenant POS system, I chose the polyrepo approach because it seemed simpler. Here's what I learned:

Real-World Polyrepo Structure

my-pos-system/
├── pos-api (GitHub repo)
│   ├── src/
│   ├── package.json
│   └── .github/workflows/
├── pos-web (GitHub repo)
│   ├── src/
│   ├── package.json
│   └── .github/workflows/
├── pos-mobile-api (GitHub repo)
│   ├── src/
│   ├── package.json
│   └── .github/workflows/
├── pos-notification-service (GitHub repo)
│   ├── src/
│   ├── package.json
│   └── .github/workflows/
└── pos-shared (GitHub repo)
    ├── src/
    ├── package.json
    └── .github/workflows/

Managing Shared Code in Polyrepo

The Challenge: All services needed shared TypeScript types and utilities.

My Solution: Private npm Registry

1. Create Shared Package:

// pos-shared/src/types/user.ts
export interface User {
  id: string;
  email: string;
  tenantId: string;
  role: 'admin' | 'manager' | 'cashier';
}

export interface AuthToken {
  userId: string;
  tenantId: string;
  expiresAt: Date;
}

// pos-shared/package.json
{
  "name": "@my-company/pos-shared",
  "version": "1.2.3",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

2. Publish to GitHub Packages:

# In pos-shared repository
npm run build
npm version patch  # 1.2.3 → 1.2.4
npm publish

# Output:
# + @my-company/[email protected]

3. Use in Other Services:

# In pos-api repository
npm install @my-company/[email protected]

// pos-api/src/services/auth.service.ts
import { User, AuthToken } from '@my-company/pos-shared';

export class AuthService {
  async authenticate(email: string, password: string): Promise<AuthToken> {
    // Use shared types
  }
}

Polyrepo Workflow Example

Scenario: Add new field to User type

# Step 1: Update shared package
cd pos-shared
git checkout -b add-user-phone-field

# Edit types
# pos-shared/src/types/user.ts

export interface User {
  id: string;
  email: string;
  phone?: string; // New field
  tenantId: string;
  role: 'admin' | 'manager' | 'cashier';
}

# Commit and publish
git add src/types/user.ts
git commit -m "feat: add phone field to User type"
git push -u origin add-user-phone-field

# Create PR, get review, merge

# Publish new version
git checkout main
git pull origin main
npm version minor  # 1.2.4 → 1.3.0
npm publish

# Step 2: Update pos-api
cd ../pos-api
git checkout -b update-shared-types

npm install @my-company/[email protected]
git add package.json package-lock.json
git commit -m "chore: update shared types to v1.3.0"

# Update code to use new field
git add src/services/user.service.ts
git commit -m "feat: add phone number support"
git push -u origin update-shared-types

# Create PR, review, merge, deploy

# Step 3: Repeat for other services...
cd ../pos-web
# Same process

cd ../pos-mobile-api
# Same process

cd ../pos-notification-service
# Same process

Advantages of Polyrepo

1. Clear Ownership and Boundaries

Each service has its own repository, making ownership obvious:

# Different teams can own different repos
team-payments owns payment-service
team-users owns user-service
team-inventory owns inventory-service

2. Independent CI/CD Pipelines

# payment-service/.github/workflows/deploy.yml
name: Deploy Payment Service
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test
      - name: Deploy to production
        run: npm run deploy

Each service deploys independently—if user-service is broken, payment-service can still deploy.

3. Smaller Repository Size

# Clone only what you need
git clone https://github.com/my-company/payment-service.git

# Not the entire codebase

4. Flexible Technology Choices

payment-service/     (Node.js + TypeScript)
inventory-service/   (Node.js + TypeScript)
analytics-service/   (Python + FastAPI)
ml-service/          (Python + PyTorch)

Different services can use different languages and frameworks.

Disadvantages of Polyrepo

1. Dependency Management Nightmare

The pain I felt most acutely:

# Breaking change in shared library
pos-shared v2.0.0 released

# Now I need to update 5 repositories
pos-api: still on v1.3.0 ❌
pos-web: still on v1.3.0 ❌
pos-mobile-api: still on v1.3.0 ❌
pos-notification-service: still on v1.3.0 ❌
pos-admin-portal: still on v1.3.0 ❌

# 5 PRs, 5 reviews, 5 deployments needed

2. Code Duplication

Even with shared packages, some duplication creeps in:

// pos-api/src/middleware/error-handler.ts
export const errorHandler = (err, req, res, next) => {
  // Custom error handling logic
};

// pos-web-api/src/middleware/error-handler.ts
export const errorHandler = (err, req, res, next) => {
  // Almost identical code, slightly different
};

3. Difficult Refactoring Across Services

Refactoring that touches multiple services requires coordination:

# Want to rename "tenantId" to "organizationId" everywhere
# Requires changes in:
pos-shared (types)
pos-api (database, logic)
pos-web (frontend)
pos-mobile-api (API endpoints)
pos-notification-service (templates)

# Must be coordinated carefully or things break

4. Complex Cross-Service Changes

# Feature: Add multi-currency support
# Requires changes in:
1. pos-shared (add Currency type)
2. pos-api (database schema, calculations)
3. pos-payment-service (payment processing)
4. pos-web (UI for currency selection)
5. pos-notification-service (format prices in emails)

# Need to create, review, and merge 5 PRs in correct order
# Very time-consuming!

Monorepo: The Alternative Approach

After the polyrepo pain, I migrated one of my projects to a monorepo. Here's what I learned:

Real-World Monorepo Structure

pos-monorepo/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── deploy.yml
├── services/
│   ├── api/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── web/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── mobile-api/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── notification/
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── packages/
│   ├── shared-types/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── auth-lib/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── database-lib/
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── package.json (root)
├── turbo.json (or nx.json)
└── pnpm-workspace.yaml

Setting Up a Monorepo with pnpm

1. Initialize Monorepo:

mkdir pos-monorepo
cd pos-monorepo

# Initialize git
git init

# Initialize pnpm workspace
npm install -g pnpm
pnpm init

2. Create Workspace Configuration:

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

3. Root package.json:

{
  "name": "pos-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test",
    "dev": "turbo run dev --parallel",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "^1.10.0",
    "typescript": "^5.0.0"
  }
}

4. Create Shared Package:

mkdir -p packages/shared-types
cd packages/shared-types
pnpm init

// packages/shared-types/package.json
{
  "name": "@pos/shared-types",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  }
}

// packages/shared-types/src/index.ts
export interface User {
  id: string;
  email: string;
  phone?: string;
  tenantId: string;
  role: 'admin' | 'manager' | 'cashier';
}

export interface Product {
  id: string;
  name: string;
  price: number;
  currency: string;
}

5. Create Service:

mkdir -p services/api
cd services/api
pnpm init

// services/api/package.json
{
  "name": "@pos/api",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "dev": "ts-node-dev src/index.ts",
    "test": "jest"
  },
  "dependencies": {
    "@pos/shared-types": "workspace:*",
    "express": "^4.18.0"
  }
}

// services/api/src/services/user.service.ts
import { User } from '@pos/shared-types';  // Direct import!

export class UserService {
  async getUser(id: string): Promise<User> {
    // No need to publish/install package
    // Changes to shared-types are immediately available
  }
}

6. Install Dependencies:

# From root
pnpm install

# pnpm creates symlinks between packages
# packages/shared-types is linked to services/api/node_modules/@pos/shared-types

Monorepo Workflow Example

Scenario: Add multi-currency support (same feature as polyrepo example)

# ONE repository, ONE branch, ONE PR!
git checkout -b feature/multi-currency

# 1. Add Currency type to shared package

// packages/shared-types/src/index.ts
export type Currency = 'USD' | 'EUR' | 'GBP' | 'JPY';

export interface Product {
  id: string;
  name: string;
  price: number;
  currency: Currency;  // Update
}

export interface Payment {
  amount: number;
  currency: Currency;  // New
}

# 2. Update API service

// services/api/src/services/product.service.ts
import { Product, Currency } from '@pos/shared-types';

export class ProductService {
  async createProduct(name: string, price: number, currency: Currency): Promise<Product> {
    // Implementation - types are already available!
  }
}

# 3. Update Web service

// services/web/src/components/ProductForm.tsx
import { Currency } from '@pos/shared-types';

export const ProductForm = () => {
  const [currency, setCurrency] = useState<Currency>('USD');
  // Implementation
};

# 4. Update Notification service

// services/notification/src/formatters/price.ts
import { Currency } from '@pos/shared-types';

export const formatPrice = (amount: number, currency: Currency): string => {
  // Implementation
};

# 5. Commit everything together
git add .
git commit -m "feat: add multi-currency support across all services"

# 6. Push and create ONE pull request
git push -u origin feature/multi-currency

# ONE review, ONE merge, coordinated deployment!

Advantages of Monorepo

1. Atomic Changes Across Multiple Services

# Single commit, everything stays in sync
git commit -m "refactor: rename tenantId to organizationId everywhere"

# Changed files:
# packages/shared-types/src/types.ts
# services/api/src/models/user.model.ts
# services/api/src/services/tenant.service.ts
# services/web/src/components/TenantSelector.tsx
# services/notification/src/templates/email.ts

# Everything is updated together - no version mismatches!

2. Simplified Dependency Management

# Update TypeScript version for entire monorepo
pnpm add -D [email protected] -w

# All services use same version automatically

3. Code Sharing is Trivial

// No publishing required!
import { User } from '@pos/shared-types';
import { authenticateUser } from '@pos/auth-lib';
import { DatabaseClient } from '@pos/database-lib';

// Changes to any package are immediately available

4. Easier Refactoring

# Refactor across entire codebase
# Find all usages of old function and update
git grep "oldFunctionName"
# Update all occurrences
git commit -m "refactor: rename oldFunctionName to newFunctionName"

# TypeScript compiler ensures everything works together

5. Unified CI/CD with Smart Builds

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Build (only changed packages)
        run: pnpm turbo run build
      
      - name: Test (only changed packages)
        run: pnpm turbo run test

Turbo/Nx only builds and tests what changed!

6. Consistent Tooling

// Root .eslintrc.json applies to all packages
{
  "extends": ["eslint:recommended"],
  "rules": {
    "no-console": "error"
  }
}

// Root .prettierrc applies to all packages
{
  "semi": true,
  "singleQuote": true
}

Disadvantages of Monorepo

1. Large Repository Size

git clone https://github.com/my-company/pos-monorepo.git

# Downloads entire history of all services
# Can be large (100MB+ for established projects)

Mitigation: Use Git shallow clones in CI/CD:

git clone --depth 1 https://github.com/my-company/pos-monorepo.git

2. Requires Tooling (Turbo, Nx, Rush)

# Without tools, this is slow:
npm run test  # Runs tests in ALL packages

# With Turbo:
turbo run test  # Only tests changed packages

3. All-or-Nothing Access Control

# In polyrepo: can give contractor access to only payment-service

# In monorepo: contractor sees entire codebase
# Mitigation: Use separate repo for sensitive services

4. Risk of Tight Coupling

// Easy to create dependencies between services

// services/api/src/controllers/user.controller.ts
import { InternalHelper } from '../../inventory/src/utils/helper';
// ⚠️ API service now depends on inventory internals!

// Should use shared package instead:
import { Helper } from '@pos/shared-utils';

5. CI/CD Complexity

# Need to detect which services changed and deploy only those
# .github/workflows/deploy.yml
- name: Detect changed services
  id: changes
  run: |
    if git diff --name-only HEAD~1 | grep -q "services/api/"; then
      echo "api_changed=true" >> $GITHUB_OUTPUT
    fi

- name: Deploy API
  if: steps.changes.outputs.api_changed == 'true'
  run: pnpm --filter @pos/api deploy

Monorepo Tools Comparison

Turbo (My Preferred Choice)

npm install turbo -D

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "dev": {
      "cache": false
    }
  }
}

Pros:

• Simple setup

• Fast (caching and parallelization)

• Great for TypeScript projects

• Works with npm, yarn, pnpm

Cons:

• Less features than Nx

• Relatively new

Nx

npx create-nx-workspace@latest

Pros:

• Powerful code generation

• Advanced dependency graph

• Plugin ecosystem

• Great for large teams

Cons:

• Steeper learning curve

• More opinionated

• Heavier setup

Lerna (Legacy)

npm install lerna -D

Pros:

• Battle-tested

• Simple concepts

Cons:

• Slower than modern tools

• Less active development

• No built-in caching

My Recommendation: Start with Turbo for simplicity, migrate to Nx if you need advanced features.

Hybrid Approach: The Best of Both Worlds

In my current project, I use a hybrid approach:

Structure

GitHub Organization: my-company
├── platform-monorepo (repo)
│   ├── services/
│   │   ├── api/
│   │   ├── web/
│   │   └── mobile-api/
│   └── packages/
│       ├── shared-types/
│       └── auth-lib/
├── analytics-service (repo)  # Separate: different team, different tech stack
├── ml-service (repo)          # Separate: Python, different deployment
└── infrastructure (repo)      # Separate: Terraform, accessed by ops team

When to Separate

Keep in monorepo:

• Services that change together frequently

• Services sharing types and utilities

• Services owned by same team

• Services with similar tech stack

Separate repository:

• Services with different tech stacks (Python vs Node.js)

• Services owned by completely different teams

• Services with different security/access requirements

• Infrastructure code (Terraform, Kubernetes manifests)

Decision Framework: Choosing Your Strategy

Choose Monorepo When:

✅ Team works on multiple related services ✅ Frequent changes span multiple services ✅ Sharing code between services is common ✅ Atomic cross-service changes are important ✅ Team size: small to medium (1-20 developers) ✅ Similar tech stack across services

Example: SaaS product with microservices (API, web, mobile)

Choose Polyrepo When:

✅ Clear service boundaries and independence ✅ Services rarely change together ✅ Different teams own different services ✅ Different tech stacks per service ✅ Large organization (100+ developers) ✅ Services have different release schedules

Example: Large enterprise with many independent products

Choose Hybrid When:

✅ Some services are tightly coupled, others independent ✅ Multiple tech stacks in use ✅ Different teams with different workflows ✅ Some services have different security requirements

Example: Platform with core services in monorepo + specialized services in separate repos

Migrating from Polyrepo to Monorepo

If you're considering migration, here's how I did it:

# 1. Create monorepo structure
mkdir pos-monorepo
cd pos-monorepo
pnpm init
git init

# 2. Create workspace config
echo "packages:
  - 'services/*'
  - 'packages/*'" > pnpm-workspace.yaml

# 3. Move first service (preserving git history)
git remote add api-origin https://github.com/my-company/pos-api.git
git fetch api-origin
git merge --allow-unrelated-histories api-origin/main -m "merge: add pos-api"
mkdir -p services
git mv * services/api/  # Move files

# 4. Repeat for other services

# 5. Create shared packages from duplicated code

# 6. Update imports and dependencies

# 7. Set up Turbo/Nx

# 8. Configure CI/CD for monorepo

Conclusion

Both monorepo and polyrepo strategies have their place in modern software development. From my experience:

Monorepo Benefits:

• Atomic cross-service changes

• Simplified dependency management

• Easy code sharing

• Better refactoring capabilities

Polyrepo Benefits:

• Clear ownership boundaries

• Independent CI/CD pipelines

• Smaller repository size

• Flexible technology choices

My Recommendation:

• Start with monorepo for new projects with related services

• Use polyrepo for truly independent services or different teams

• Consider hybrid for complex organizations

In Part 4, we'll explore GitHub best practices and collaboration patterns, including pull request workflows, code reviews, and GitHub Actions automation.

---

Key Takeaways:

• Monorepo excels at coordinating changes across services

• Polyrepo provides independence and clear boundaries

• Hybrid approach combines benefits of both

• Use tools like Turbo or Nx for monorepo management

• Choose based on team structure and service coupling

Remember: You can always migrate—start simple and evolve as needed!