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

bash

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

yaml

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

yaml

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

yaml

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

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

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

Projects control inheritance:

yaml

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

Task Options

yaml

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

yaml

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

Toolchain Configuration

yaml

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

yaml

# 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

yaml

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

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

Affected Detection

bash

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

bash

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)

bash

# 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