Monorepo README Template

Structuring a Monorepo README

Monorepo READMEs face a unique challenge: they must document the overall project structure while directing readers to individual package documentation. The root README serves as a map and entry point.

Project Structure

The most important section is a clear directory tree:

my-monorepo/
  packages/
    core/          # Core library (@myorg/core)
    cli/           # CLI tool (@myorg/cli)
    web/           # Web application
    docs/          # Documentation site
  configs/
    eslint/        # Shared ESLint config
    tsconfig/      # Shared TypeScript config

Package Overview Table

Provide a quick reference for all packages:

Package	Version	Description
@myorg/core	2.1.0	Core library with business logic
@myorg/cli	1.5.0	Command-line interface
@myorg/web	-	Web application (not published)
@myorg/docs	-	Documentation site

Getting Started

Monorepo setup typically involves:

# Clone the repository
git clone https://github.com/myorg/monorepo.git
cd monorepo

# Install all dependencies (hoisted)
npm install

# Build all packages in dependency order
npm run build

Working with Individual Packages

Show how to run commands for specific packages:

# Start the web app
npm run dev --workspace=packages/web

# Run tests for core
npm test --workspace=packages/core

# Build just the CLI
npm run build --workspace=packages/cli

Cross-Package Dependencies

Explain how packages depend on each other:

@myorg/cli --> @myorg/core
@myorg/web --> @myorg/core
@myorg/docs --> @myorg/core (for API docs generation)

Versioning and Publishing

Document the release process, especially if using tools like Changesets or Lerna:

# Create a changeset
npx changeset

# Version packages
npx changeset version

# Publish to npm
npx changeset publish