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

```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