What is a Monorepo?

From SCRUM-11: Learn what is a monorepo

My Learning Notes

Workspace is helpful when we use TypeScript - sub-repos will refer to root type definition.

Definition

A monorepo (mono repository) is a single Git repository that contains multiple projects/packages.

my-monorepo/
├── packages/
│   ├── shared/      # Shared utilities
│   ├── web-app/     # Web application
│   └── extension/   # Browser extension
├── package.json     # Root package.json
└── tsconfig.json    # Shared TypeScript config

Monorepo vs Multi-repo

Aspect	Monorepo	Multi-repo
Code sharing	Easy - import directly	Hard - publish packages
Consistency	One set of configs	Multiple configs to sync
Dependencies	Shared, deduplicated	Duplicated per repo
CI/CD	One pipeline	Multiple pipelines
Repo size	Larger	Smaller per repo

Why Monorepo for VocabPal?

1. Shared types - Same interfaces in extension and web app
2. Shared services - Same Firebase services everywhere
3. Consistent tooling - One ESLint, one TypeScript config
4. Atomic changes - Update shared code and consumers together
5. TypeScript benefits - Sub-repos reference root type definitions

Tools for Monorepos

• npm workspaces - Built into npm (what we use)
• Yarn workspaces - Similar, for Yarn users
• pnpm workspaces - Fast, efficient
• Nx - Advanced build system
• Turborepo - Fast builds with caching
• Lerna - Package publishing

Key Concepts

Workspace

A package within the monorepo that can be:

• Published to npm
• Used by other workspaces
• Both

Hoisting

Dependencies are "hoisted" to the root node_modules, so they're shared (and deduplicated) across workspaces.

Root Type Definitions

With TypeScript, child packages can reference types defined in the root tsconfig.json, ensuring consistency across the monorepo.

Key Takeaways

• Monorepo = multiple projects in ONE repository
• Workspaces = npm feature to manage multiple package.json files
• Root package.json = orchestrates child packages
• Shared code = write once, use in multiple packages
• TypeScript configs can be shared across packages