moon - Polyglot Monorepo Build System

moon is a Rust-based repository management, task orchestration, and build system for polyglot monorepos. It provides smart caching, dependency-aware task execution, and unified toolchain management.

moon v2 is now available. Run moon migrate v2 to migrate. See references/v2-migration.md for breaking changes.

When to Use moon

• Managing monorepos with multiple projects/packages
• Orchestrating tasks across projects with dependencies
• Caching build outputs for faster CI/local builds
• Managing toolchain versions (Node.js, Rust, Python, Go, etc.)
• Generating project and action graphs

Quick Reference

Core Commands

moon run <target>          # Run task(s)
moon run :lint             # Run in all projects
moon run '#tag:test'       # Run by tag
moon ci                    # CI-optimized execution
moon check --all           # Run all build/test tasks
moon query projects        # List projects
moon project-graph         # Visualize dependencies

Target Syntax

Pattern	Description
project:task	Specific project and task
:task	All projects with this task
#tag:task	Projects with tag
^:task	Upstream dependencies (in deps)
~:task	Current project (in configs)

Configuration Files

File	Purpose
.moon/workspace.yml	Workspace settings, project discovery
.moon/toolchains.yml	Language versions, package managers (v2)
.moon/tasks/*.yml	Global inherited tasks (v2)
moon.yml	Project-level config and tasks

v2 Note: .moon/toolchain.yml → .moon/toolchains.yml (plural), .moon/tasks.yml → .moon/tasks/*.yml

Workspace Configuration

# .moon/workspace.yml
$schema: "https://moonrepo.dev/schemas/workspace.json"

projects:
  - "apps/*"
  - "packages/*"

vcs:
  manager: "git"
  defaultBranch: "main"

runner:
  archivableTargets:
    - ":build"
  cacheLifetime: "7 days"

Project Configuration

# moon.yml
$schema: "https://moonrepo.dev/schemas/project.json"

language: "typescript"
layer: "application" # v2: 'type' renamed to 'layer'
stack: "frontend"
tags: ["react", "graphql"]

dependsOn:
  - "shared-utils"
  - id: "api-client"
    scope: "production"

fileGroups:
  sources:
    - "src/**/*"
  tests:
    - "tests/**/*"

tasks:
  build:
    command: "vite build"
    inputs:
      - "@group(sources)"
    outputs:
      - "dist"
    deps:
      - "^:build"

  dev:
    command: "vite dev"
    preset: "server"

  # v2: Use 'script' for shell features (pipes, redirects)
  lint:
    script: "eslint . && prettier --check ."

  test:
    command: "vitest run"
    inputs:
      - "@group(sources)"
      - "@group(tests)"

Layer Types (v2)

Layer	Description
application	Apps, services
library	Shareable code
tool	CLIs, scripts
automation	E2E/integration tests
scaffolding	Templates, generators
configuration	Infra, config

Task Configuration

Task Fields

Field	Description
command	Command to execute (string or array)
args	Additional arguments
deps	Task dependencies
inputs	Files for cache hashing
outputs	Files to cache
env	Environment variables
extends	Inherit from another task
preset	server or utility

Task Inheritance

Tasks can be inherited globally via .moon/tasks/*.yml:

# .moon/tasks/node.yml
inheritedBy:
  toolchains: ["javascript", "typescript"]

fileGroups:
  sources: ["src/**/*"]

tasks:
  lint:
    command: "eslint ."
    inputs: ["@group(sources)"]

Projects control inheritance:

# moon.yml
workspace:
  inheritedTasks:
    include: ["lint", "test"]
    exclude: ["deploy"]
    rename:
      buildApp: "build"

Task Options

tasks:
  example:
    command: "cmd"
    options:
      cache: true # Enable caching
      runInCI: "affected" # affected, always, only, false
      persistent: true # Long-running process
      retryCount: 2 # Retry on failure
      timeout: 300 # Seconds
      mutex: "resource" # Exclusive lock
      priority: "high" # critical, high, normal, low

Input Tokens

inputs:
  - "@group(sources)" # File group
  - "@globs(tests)" # Glob patterns
  - "/tsconfig.base.json" # Workspace root file
  - "$NODE_ENV" # Environment variable

Toolchain Configuration

# .moon/toolchains.yml (v2: plural)
$schema: "https://moonrepo.dev/schemas/toolchains.json"

# JavaScript ecosystem (v2: required for node/bun/deno)
javascript:
  packageManager: "pnpm"
  inferTasksFromScripts: false

node:
  version: "20.10.0"

pnpm:
  version: "8.12.0"

# Alternative runtimes
bun:
  version: "1.0.0"

deno:
  version: "1.40.0"

typescript:
  syncProjectReferences: true
  routeOutDirToCache: true

rust:
  version: "1.75.0"
  bins: ["cargo-nextest", "cargo-llvm-cov"]

go:
  version: "1.21.0"

python:
  version: "3.12.0"

Toolchain Tiers

Tier	Description	Examples
3	Full management	Node.js, Bun, Deno, Rust, Go, Python
2	Ecosystem integration	PHP, Ruby
1	Project categorization	Bash, Batch
0	System execution	Custom tools

CI Integration

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # Required for affected detection

- uses: moonrepo/setup-toolchain@v0
  with:
    auto-install: true

- run: moon ci :build :test

- uses: moonrepo/run-report-action@v1
  if: success() || failure()
  with:
    access-token: ${{ secrets.GITHUB_TOKEN }}

Parallelization with Matrix

strategy:
  matrix:
    shard: [0, 1, 2, 3]

steps:
  - run: moon ci --job ${{ matrix.shard }} --job-total 4

Affected Detection

moon run :test --affected             # Only affected projects
moon run :lint --affected --status staged  # Only staged files
moon ci :test --base origin/main      # Compare against base
moon query changed-files              # v2: renamed from touched-files

Docker Support

moon docker scaffold <project>     # Generate Docker layers
moon docker setup                  # Install toolchain in Docker
moon docker prune                  # Prune for production
moon docker file <project>         # Generate Dockerfile

Moon Query Language (MQL)

# Filter projects
moon query projects "language=typescript && projectType=library"
moon run :build --query "tag=react"

# Operators: =, !=, ~, !~, &&, ||
# Fields: project, language, stack, tag, task, taskType

Additional Resources

For detailed configuration options, consult:

• references/workspace-config.md - Complete workspace.yml reference
• references/task-config.md - Task configuration and inheritance patterns
• references/v2-migration.md - v1 to v2 migration guide
• references/cli-reference.md - Full CLI command reference

Examples

• examples/workspace.yml - Complete workspace configuration
• examples/moon.yml - Full project configuration
• examples/ci-workflow.yml - GitHub Actions CI workflow