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 variab

...

moon

SKILL.md