moon

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

Configuration Files

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:
  client: 'git'
  defaultBranch: 'main'

pipeline:
  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)

Task Configuration

Task Fields

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

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