Overview

moonrepo (moon) is a Rust-based monorepo management tool and task runner. It understands your project dependency graph, runs tasks in the correct order with caching, manages toolchain versions (Node.js, Bun, etc.), and generates CI pipelines automatically. Faster and more deterministic than Turborepo, with built-in toolchain management that Nx doesn't have.

When to Use

Managing a monorepo with multiple packages/apps
Need deterministic task execution with dependency-aware ordering
Want consistent toolchain versions across the team
CI is slow because it builds everything on every PR
Need better caching than npm scripts provide

Instructions

Setup

bash

# Install moon CLI
npm install -D @moonrepo/cli

# Initialize in your monorepo
moon init

Workspace Configuration

yaml

# .moon/workspace.yml — Monorepo root config
projects:
  - "apps/*"
  - "packages/*"

vcs:
  manager: git
  defaultBranch: main

runner:
  cacheLifetime: 7d
  logStyle: stream

Toolchain Management

yaml

# .moon/toolchain.yml — Pin Node.js and package manager versions
node:
  version: "20.11.0"
  packageManager: pnpm
  pnpm:
    version: "9.1.0"

# Automatically downloads and uses these exact versions
# No more "works on my machine" — everyone uses the same toolchain

Project Configuration

yaml

# apps/web/moon.yml — Project-level config
type: application
language: typescript

dependsOn:
  - "packages/ui"
  - "packages/shared"

tasks:
  dev:
    command: next dev
    local: true       # Only runs locally, not in CI

  build:
    command: next build
    inputs:
      - "src/**/*"
      - "package.json"
      - "next.config.js"
    outputs:
      - ".next"
    deps:
      - "packages/ui:build"    # Build ui package first
      - "packages/shared:build"

  test:
    command: vitest run
    inputs:
      - "src/**/*"
      - "tests/**/*"

  lint:
    command: oxlint src/
    inputs:
      - "src/**/*"

yaml

# packages/ui/moon.yml — Shared UI library
type: library
language: typescript

tasks:
  build:
    command: tsup
    inputs:
      - "src/**/*"
      - "tsup.config.ts"
    outputs:
      - "dist"

  test:
    command: vitest run
    inputs:
      - "src/**/*"
      - "tests/**/*"

Run Tasks

bash

# Run a task in a specific project
moon run web:build

# Run task across all projects that have it
moon run :test

# Run with dependency graph (builds deps first)
moon run web:build  # Automatically builds packages/ui first

# Check what would run (dry run)
moon run web:build --dryRun

# Run affected tasks only (based on git diff)
moon run :test --affected

CI Optimization

yaml

# .github/workflows/ci.yml — Only run what changed
name: CI
on: [pull_request]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for affected detection

      - uses: moonrepo/setup-toolchain@v0

      - run: moon ci  # Runs all affected tasks in optimal order

bash

# moon ci does:
# 1. Detects which files changed in the PR
# 2. Determines which projects are affected
# 3. Runs only the affected tasks in dependency order
# 4. Uses cache for unchanged outputs

Examples

Example 1: Set up a new monorepo

User prompt: "I have a Next.js app and 3 shared packages. Set up a monorepo with proper task orchestration."

The agent will initialize moon, configure workspace projects, define tasks with proper inputs/outputs/deps, and set up CI with affected detection.

Example 2: Migrate from Turborepo

User prompt: "Our Turborepo setup is getting complex. Migrate to moonrepo."

The agent will translate turbo.json pipeline to moon task configs, set up toolchain management, and configure CI with moon's affected detection.

Guidelines

inputs and outputs for caching — define what files affect a task and what it produces
deps for task ordering — "packages/ui:build" runs before "web:build"
--affected for CI — only run tasks for changed projects
moon ci is the CI command — handles affected detection, ordering, and caching
Toolchain pinning — everyone uses exactly the same Node.js/pnpm version
type: application vs library — affects dependency graph behavior
local: true for dev tasks — skipped in CI automatically
Project references via dependsOn — moon understands the monorepo graph
Cache is content-addressed — same inputs = cache hit, regardless of branch

moonrepo

Usage

Getting Started

Example Prompts

Documentation

Overview

When to Use

Instructions

Setup

Workspace Configuration

Toolchain Management

Project Configuration

Run Tasks

CI Optimization

Examples

Example 1: Set up a new monorepo

Example 2: Migrate from Turborepo

Guidelines

Information

Use Cases