moonrepo

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

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

# Initialize in your monorepo
moon init

Workspace Configuration

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

vcs:
  manager: git
  defaultBranch: main

runner:
  cacheLifetime: 7d
  logStyle: stream

Toolchain Management

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

# 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/**/*"

# 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

# 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

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

# 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