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

Moon CLI Reference

Complete reference for all moon CLI commands.

Task Execution

moon run

Execute targets and their dependencies.

moon run <target>... [-- <args>]

Options:

Examples:

moon run app:build
moon run :lint --affected
moon run '#frontend:test'
moon run app:test -- --coverage
moon run :build --query "language=typescript"

moon check

Run all build/test tasks for projects.

moon check [project...]
moon check --all

moon ci

CI-optimized task execution with job distribution.

moon ci [target...]

Options:

Examples:

moon ci :build :test
moon ci :test --job 0 --job-total 4
moon ci --base origin/main --head HEAD

Query Commands

moon query projects

moon query projects [mql]
moon query projects --affected
moon query projects --tags frontend
moon query projects "language=typescript"

moon query tasks

moon query tasks [mql]
moon query tasks --affected
moon query tasks "task~dev-*"

moon query touched-files

moon query touched-files
moon query touched-files --status modified,staged
moon query touched-files --base main --head HEAD

moon query hash

moon query hash <hash>
moon query hash-diff <left> <right>

Graph Visualization

moon project-graph

moon project-graph [project]
moon project-graph --dot > graph.dot
moon project-graph app --dependents

moon action-graph

moon action-graph [target]
moon action-graph app:build --dot

Workspace Management

moon init

moon init
moon init node
moon init --minimal
moon init --to ./app

moon sync

moon sync projects     # Sync all projects
moon sync hooks        # Sync VCS hooks

moon setup

moon setup             # Install toolchain

moon generate

moon generate <template> [dest] [-- vars]
moon generate npm-package ./packages/foo -- --name "@company/foo"
moon templates         # List available templates

Docker Commands

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

Toolchain Commands

moon bin <tool>                  # Get tool binary path
moon toolchain add <name>        # Add toolchain
moon upgrade                     # Upgrade moon

Extension Commands

moon ext <id> [-- args]          # Run extension
moon ext migrate-nx              # Migrate from Nx
moon ext migrate-turborepo       # Migrate from Turborepo

Utility Commands

moon completions [--shell <shell>]  # Generate completions

Global Flags

Moon Query Language (MQL)

Operators

Fields

Projects: project, projectAlias, projectSource, projectType, language, layer, stack, tag

Tasks: task, taskCommand, taskType, taskToolchain

Examples

moon query projects "language=typescript && projectType=library"
moon run :build --query "tag=react"
moon query projects "projectSource~packages/*"

Moon Task Configuration Reference

Complete reference for task configuration in moon.yml and .moon/tasks.yml.

Global Task Inheritance

Configuration Hierarchy

.moon/tasks.yml              # Inherited by ALL projects (legacy)
.moon/tasks/*.yml            # Conditional inheritance based on conditions
└── moon.yml                 # Project-level tasks (override/merge)

Global Tasks File Structure

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

# External configuration to extend
extends: "https://raw.githubusercontent.com/org/repo/main/.moon/tasks/base.yml"

# Conditions for which projects inherit these tasks
inheritedBy:
  toolchains:
    or: ["javascript", "typescript"]
  stacks: ["frontend", "backend"]
  layers: ["application", "library"]

# File groups inherited by matching projects
fileGroups:
  configs:
    - "*.config.{js,cjs,mjs,ts}"
    - "tsconfig*.json"
  sources:
    - "src/**/*"
    - "types/**/*"
  tests:
    - "tests/**/*"
    - "**/__tests__/**/*"
    - "**/*.test.{ts,tsx}"

# Default options for all tasks in this file
taskOptions:
  cache: true
  runInCI: "affected"

# Implicit dependencies added to ALL tasks
implicitDeps:
  - "^:build" # Run upstream builds first

# Implicit inputs added to ALL tasks
implicitInputs:
  - "package.json"
  - "/tsconfig.base.json"

# Tasks inherited by matching projects
tasks:
  lint:
    command: "eslint ."
    inputs:
      - "@group(sources)"

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

Inheritance Conditions

Projects inherit tasks when ALL specified conditions match (AND logic between condition types):

Condition Operators

inheritedBy:
  # Simple array (OR within condition)
  stacks: ["frontend", "backend"]

  # With operators (tags and toolchains support this)
  toolchains:
    or: ["javascript", "typescript"] # Match any
    not: ["ruby"] # Exclude

  tags:
    and: ["react", "typescript"] # Match all
    or: ["web", "mobile"] # Match any
    not: ["deprecated"] # Exclude

Scoped Task Files

Convention-based file names for automatic inheritance:

Task Definition

tasks:
  build:
    # Command to execute (string or array)
    command: 'webpack build --mode production'
    # OR
    command:
      - 'webpack'
      - 'build'
      - '--mode'
      - 'production'

    # Additional arguments
    args:
      - '--color'
      - '--progress'

    # Alternative: shell script (supports pipes, redirects)
    script: 'rm -rf dist && webpack build > build.log'

    # Environment variables
    env:
      NODE_ENV: 'production'
      API_URL: '${BACKEND_URL}/api'

    # Task dependencies
    deps:
      - 'shared:build'        # Specific project
      - '~:codegen'           # Same project
      - '^:build'             # All upstream deps
      - target: 'optional:task'
        optional: true        # Don't fail if missing

    # Input files for hash calculation
    inputs:
      - 'src/**/*'
      - '@group(sources)'     # File group
      - '/tsconfig.base.json' # Workspace root
      - '$NODE_ENV'           # Env variable

    # Output files to cache
    outputs:
      - 'dist'
      - 'build/**/*.js'

    # Inherit from another task
    extends: 'base-build'

    # Task preset (server, watcher)
    preset: 'server'

    # Toolchain override
    toolchain: 'node'

    # Task options
    options:
      cache: true
      runInCI: 'affected'

Task Options Reference

Caching

Execution

Shell

Environment

Output

Special Modes

Merge Strategies

Token Variables

Project Variables

Environment Variables

Task Extension (extends)

The extends field allows tasks to inherit from sibling tasks or globally inherited tasks.

Basic Extension

tasks:
  # Base task
  lint:
    command: "eslint ."
    inputs:
      - "@group(sources)"
    options:
      cache: true

  # Extended task - inherits all settings from lint
  lint-fix:
    extends: "lint"
    args: "--fix"
    preset: "utility" # Disable cache, enable interactive

Extension with Overrides

tasks:
  build:
    command: "vite build"
    inputs:
      - "@group(sources)"
      - "@group(configs)"
    outputs:
      - "dist"
    env:
      NODE_ENV: "production"
    options:
      cache: true

  # Development build - overrides specific settings
  build-dev:
    extends: "build"
    args: "--mode development"
    env:
      NODE_ENV: "development"
    options:
      cache: false
      mergeArgs: "replace" # Don't append, replace args

Extending Inherited Tasks

Project tasks can extend globally inherited tasks:

# .moon/tasks/node.yml (global)
tasks:
  test:
    command: 'vitest run'
    inputs: ['@group(sources)', '@group(tests)']

# apps/web/moon.yml (project)
tasks:
  test-e2e:
    extends: 'test'           # Extends the inherited 'test' task
    args: '--project=e2e'
    options:
      timeout: 600

Task Presets

Presets are predefined option sets for common task patterns.

Available Presets

Auto-Applied Presets

Tasks named dev, start, or serve automatically get the server preset.

Preset Usage

tasks:
  # Long-running development server
  dev:
    command: "vite dev"
    preset: "server" # No cache, streams output, persistent

  # Interactive utility command
  migrate:
    command: "prisma migrate dev"
    preset: "utility" # No cache, streams output, interactive

  # Override preset defaults
  watch:
    command: "tsc --watch"
    preset: "server"
    options:
      runInCI: "skip" # Override the preset's runInCI: false

Controlling Inherited Tasks

Projects can filter, exclude, or rename inherited tasks.

Include (Allowlist)

# moon.yml
workspace:
  inheritedTasks:
    include:
      - "lint"
      - "test"
    # Only these tasks are inherited; all others excluded

Exclude (Blocklist)

workspace:
  inheritedTasks:
    exclude:
      - "deploy"
      - "publish"
    # All tasks inherited except these

Rename

workspace:
  inheritedTasks:
    rename:
      buildApplication: "build" # Use shorter name locally
      testUnit: "test"

Combined Example

# moon.yml
workspace:
  inheritedTasks:
    include: ["lint", "test", "build", "buildApplication"]
    exclude: ["test"] # Applied after include
    rename:
      buildApplication: "build" # Applied last
# Result: only 'lint' and 'build' tasks inherited

Processing Order

1. Include - Filter to only specified tasks 2. Exclude - Remove specific tasks from the filtered set 3. Rename - Apply name mappings to remaining tasks

File Groups

File groups organize related files for reuse across tasks.

Defining File Groups

fileGroups:
  # Source files
  sources:
    - "src/**/*"
    - "lib/**/*"

  # Test files
  tests:
    - "tests/**/*"
    - "**/__tests__/**/*"
    - "**/*.test.{ts,tsx,js,jsx}"
    - "**/*.spec.{ts,tsx,js,jsx}"

  # Configuration files
  configs:
    - "*.config.{js,cjs,mjs,ts}"
    - "tsconfig*.json"
    - "package.json"

  # Static assets
  assets:
    - "public/**/*"
    - "static/**/*"

  # Everything lintable
  lintable:
    - "@group(sources)"
    - "@group(tests)"
    - "@group(configs)"

  # Negation patterns
  production:
    - "src/**/*"
    - "!src/**/*.test.*"
    - "!src/**/__mocks__/**"

Using File Groups

tasks:
  lint:
    command: "eslint"
    args:
      - "@globs(lintable)" # Glob patterns as arguments
    inputs:
      - "@group(lintable)" # For cache hashing

  typecheck:
    command: "tsc --noEmit"
    inputs:
      - "@group(sources)"
      - "@group(configs)"

  test:
    command: "vitest run"
    args:
      - "@files(tests)" # Expanded file paths
    inputs:
      - "@group(sources)"
      - "@group(tests)"

Token Functions for File Groups

File Group Inheritance

File groups defined in .moon/tasks/*.yml are inherited by matching projects. Project-level groups override inherited groups of the same name.

# .moon/tasks/node.yml
fileGroups:
  sources:
    - 'src/**/*'

# apps/api/moon.yml - overrides inherited 'sources'
fileGroups:
  sources:
    - 'src/**/*'
    - 'generated/**/*'   # Project-specific addition

Merge Strategies

Control how inherited and extended task values combine.

Strategy Options

Configuring Merge Strategies

tasks:
  build:
    command: "webpack"
    args: ["--mode", "production"]
    deps: ["codegen"]
    inputs: ["src/**/*"]
    options:
      mergeArgs: "replace" # Completely replace inherited args
      mergeDeps: "prepend" # Run local deps before inherited
      mergeEnv: "append" # Add to inherited env vars
      mergeInputs: "append" # Combine with inherited inputs
      mergeOutputs: "replace" # Override inherited outputs

Merge Fields

Example: Merge Behavior

# Inherited task
tasks:
  test:
    command: 'vitest'
    args: ['run']
    deps: ['^:build']
    inputs: ['src/**/*']

# Project task with mergeArgs: 'append' (default)
tasks:
  test:
    args: ['--coverage']
    # Result: ['run', '--coverage']

# Project task with mergeArgs: 'prepend'
tasks:
  test:
    args: ['--coverage']
    options:
      mergeArgs: 'prepend'
    # Result: ['--coverage', 'run']

# Project task with mergeArgs: 'replace'
tasks:
  test:
    args: ['--coverage']
    options:
      mergeArgs: 'replace'
    # Result: ['--coverage']

Implicit Dependencies and Inputs

Always inherited regardless of merge settings.

implicitDeps

Dependencies added to ALL inherited tasks:

# .moon/tasks/node.yml
implicitDeps:
  - "^:build" # Always build dependencies first
  - "~:codegen" # Always run codegen in same project

implicitInputs

Input files added to ALL inherited tasks:

# .moon/tasks/node.yml
implicitInputs:
  - "package.json"
  - "/tsconfig.base.json" # Workspace root
  - "/.moon/toolchains.yml" # Workspace config (v2: plural)

External Configuration (extends)

Extending Remote Configuration

# .moon/tasks/node.yml
extends: "https://raw.githubusercontent.com/company/configs/main/.moon/tasks/base.yml"

# Local overrides and additions
tasks:
  custom:
    command: "custom-tool"

Extending Local Configuration

extends: "../shared/base-tasks.yml"

Versioning Remote Configs

# Pin to specific commit for stability
extends: 'https://raw.githubusercontent.com/company/configs/abc1234/.moon/tasks/base.yml'

# Or use versioned filenames
extends: 'https://raw.githubusercontent.com/company/configs/main/tasks-v2.yml'

Merge Behavior

When extending, local values take precedence. Map entries (fileGroups, tasks) merge at the top level only.

# Remote base.yml
fileGroups:
  sources:
    - 'src/**/*'
tasks:
  lint:
    command: 'eslint'

# Local override
fileGroups:
  sources:         # Completely replaces remote 'sources'
    - 'lib/**/*'
  tests:           # Added (not in remote)
    - 'tests/**/*'
tasks:
  lint:            # Completely replaces remote 'lint'
    command: 'biome lint'
  test:            # Added (not in remote)
    command: 'vitest'

runInCI Values

Common Patterns

Build with Dependencies

tasks:
  build:
    command: "tsc"
    deps:
      - "^:build" # Build all dependencies first
    inputs:
      - "@group(sources)"
    outputs:
      - "dist"

Development Server

tasks:
  dev:
    command: "vite dev"
    preset: "server" # Sets persistent, no cache, no CI

Serial Dependencies

tasks:
  deploy:
    command: "./deploy.sh"
    deps:
      - "clean"
      - "build"
      - "test"
    options:
      runDepsInParallel: false # Run in order

Conditional Execution

tasks:
  build-linux:
    command: "./build-linux.sh"
    options:
      os: "linux"

  e2e:
    command: "playwright test"
    options:
      runInCI: "always"
      timeout: 600
      retryCount: 2

Moon v2 Migration Reference

Complete guide for migrating from moon v1 to v2.

Migration Command

moon migrate v2

This automates applicable configuration changes.

Breaking Changes Summary

Configuration File Renames

Workspace Settings (.moon/workspace.yml)

Project Settings (moon.yml)

Task Settings

Token Variables

Script vs Command

Complex shell operations now require script instead of command:

# v1 - command with pipes (worked)
tasks:
  example:
    command: 'echo "foo" | grep "f"'

# v2 - must use script for shell features
tasks:
  example:
    script: 'echo "foo" | grep "f"'

When to use script:

• Pipes (|)
• Redirects (>, <, >>)
• Chaining (&&, ||, ;)
• Shell globbing
• Environment expansion in complex expressions

When to use command:

• Simple commands without shell features
• Commands with arguments

Shell Enabled by Default

Tasks now run in shells (Bash on Unix, pwsh on Windows). To disable:

tasks:
  example:
    command: "tool"
    options:
      shell: false

Project Layers (Formerly Type)

New categorization system:

Default Project

Configure fallback project when running tasks without scope:

# .moon/workspace.yml
defaultProject: "core-app"

Usage:

• :task without project scope runs on default project
• ~:task runs on closest project (previous behavior)

Toolchain Configuration Changes

v1 Structure (Nested)

# .moon/toolchain.yml (v1)
node:
  version: "20.10.0"
  packageManager: "pnpm"
  pnpm:
    version: "8.0.0"

v2 Structure (Flat)

# .moon/toolchains.yml (v2)
javascript:
  packageManager: "pnpm"
  inferTasksFromScripts: true

node:
  version: "20.10.0"

pnpm:
  version: "8.0.0"

Critical: bun, deno, and node toolchains require javascript to be enabled:

javascript: {} # Required!

bun:
  version: "1.0.0"

WASM Extensions

Built-in extensions must be explicitly enabled:

# .moon/extensions.yml
download: {}
migrate-nx: {}
migrate-turborepo: {}
unpack: {}

VCS Hooks Location

Hooks now write to .moon/hooks instead of .git/hooks.

Remote Caching

unstable_remote is now remote:

# v1
unstable_remote:
  host: "grpcs://cache.example.com"

# v2
remote:
  host: "grpcs://cache.example.com"

CLI Changes

Environment Variable Changes

• MOON_AFFECTED_FILES now uses OS path separator (: Unix, ; Windows) instead of comma

Removed Features

• x86_64-apple-darwin (Apple Intel) - Only Apple Silicon supported
• moon node command
• project.metadata setting
• hasher.batchSize setting
• experiments section
• Nested package manager config under node

MCP Protocol Changes

• Updated protocol version to 2025-11-25
• get_projects returns project fragments (not full objects)
• get_tasks returns task fragments (not full objects)
• No more includeTasks option

Deep Merge Behavior

Tasks now undergo deep merging (sequential) rather than shallow merging:

# Base task
lint:
  command: 'eslint'
  args: ['--cache']
  inputs: ['src/**/*']

# Extended task - v2 merges deeply
lint:
  args: ['--fix']  # Results in ['--cache', '--fix']

Migration Checklist

• [ ] Rename .moon/toolchain.yml to .moon/toolchains.yml
• [ ] Move .moon/tasks.yml to .moon/tasks/all.yml
• [ ] Update runner to pipeline in workspace.yml
• [ ] Update type to layer in project moon.yml files
• [ ] Update local: true to preset: server
• [ ] Update platform to toolchains in tasks
• [ ] Add javascript: {} if using node/bun/deno
• [ ] Update unstable_remote to remote
• [ ] Convert complex commands to use script
• [ ] Update CLI flags to kebab-case
• [ ] Enable required extensions in .moon/extensions.yml
• [ ] Run moon migrate v2 to automate applicable changes

Moon Workspace Configuration Reference

Complete reference for .moon/workspace.yml configuration.

Schema

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

Projects

Glob Patterns

projects:
  - "apps/*"
  - "packages/*"
  - "tools/*"
  - "!packages/deprecated-*" # Exclusion

Explicit Mapping

projects:
  sources:
    app: "apps/web"
    api: "apps/api"
  globs:
    - "packages/*"

VCS Configuration

vcs:
  client: "git" # v2: 'manager' renamed to 'client'
  provider: "github" # github, gitlab, bitbucket, other
  defaultBranch: "main"
  remoteCandidates:
    - "origin"
    - "upstream"
  hooks:
    pre-commit:
      - "moon run :lint --affected --status staged"
    pre-push:
      - "moon run :test --affected"

Note: In v2, VCS hooks write to .moon/hooks instead of .git/hooks.

Pipeline Configuration (v2)

Note: In v2, runner was renamed to pipeline.

pipeline:
  # Targets to archive for caching
  archivableTargets:
    - ":build"
    - ":test"

  # Cache settings
  cacheLifetime: "7 days"
  autoCleanCache: true

  # Output settings
  inheritColorsForPipedTasks: true
  logRunningCommand: true

  # Execution
  concurrency: 8 # Parallel task limit

  # Dependency management
  installDependencies: true
  syncProjects: true
  syncWorkspace: true

  # Process control
  killProcessThreshold: 3

Default Project (v2)

# When running :task without project scope, use this project
defaultProject: "website"

Hasher Configuration

hasher:
  # Optimization mode
  optimization: "performance" # accuracy, performance

  # Walk strategy
  walkStrategy: "vcs" # glob, vcs

  # Ignore patterns
  ignoredPatterns:
    - "**/.git/**"
    - "**/node_modules/**"

  # Batch size for hashing
  batchSize: 2500

Code Owners

codeowners:
  globalPaths:
    "/*": ["@platform-team"]
    "/apps/*": ["@product-team"]
    "/packages/*": ["@library-team"]
  orderBy: "project-source"
  sync: true # v2: 'syncOnRun' renamed to 'sync'

Constraints

constraints:
  # Enforce layer relationships
  enforceProjectTypeRelationships: true

  # Tag-based dependency rules
  tagRelationships:
    frontend:
      requires: ["shared"]
      conflicts: ["backend-only"]
    backend:
      requires: ["shared"]

Generator

generator:
  templates:
    - "./templates"
    - "npm:@company/templates"

Extensions

extensions:
  migrate-nx:
    plugin: "https://example.com/migrate-nx.wasm"
  custom:
    plugin: "file://./extensions/custom.wasm"

Remote Caching

Note: In v2, unstable_remote is now remote.

remote:
  host: "grpcs://cache.example.com"
  auth:
    token: "CACHE_TOKEN"
    headers:
      "X-Custom-Header": "value"
  cache:
    compression: "zstd"
    verifyIntegrity: true
    localReadOnly: false # Download only, no uploads (for dev)

Self-Hosted with bazel-remote

remote:
  host: "grpc://your-server:9092"

Run bazel-remote:

bazel-remote --dir /path/to/moon-cache --max_size 10 \
  --storage_mode zstd --grpc_address 0.0.0.0:9092

TLS/mTLS Configuration

remote:
  host: 'grpcs://your-host.com:9092'
  tls:
    cert: 'certs/ca.pem'
    domain: 'your-host.com'

# Or mTLS
remote:
  host: 'grpcs://your-host.com:9092'
  mtls:
    caCert: 'certs/ca.pem'
    clientCert: 'certs/client.pem'
    clientKey: 'certs/client.key'
    domain: 'your-host.com'

Third-Party Providers

# Depot
remote:
  host: "grpcs://cache.depot.dev"
  auth:
    token: "DEPOT_TOKEN"
    headers:
      "X-Depot-Org": "<org-id>"
      "X-Depot-Project": "<project-id>"

Notifier

notifier:
  webhookUrl: "https://hooks.slack.com/..."

Telemetry

telemetry: true # Enable usage telemetry

Complete Example

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

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

vcs:
  client: "git" # v2: 'manager' renamed to 'client'
  provider: "github"
  defaultBranch: "main"
  hooks:
    pre-commit:
      - "moon run :lint --affected --status staged"

pipeline: # v2: 'runner' renamed to 'pipeline'
  archivableTargets:
    - ":build"
  cacheLifetime: "7 days"
  inheritColorsForPipedTasks: true
  logRunningCommand: true
  autoCleanCache: true

hasher:
  optimization: "performance"
  walkStrategy: "vcs"

codeowners:
  globalPaths:
    "/*": ["@platform-team"]
  sync: true # v2: 'syncOnRun' renamed to 'sync'

constraints:
  enforceProjectTypeRelationships: true
  tagRelationships:
    frontend:
      requires: ["shared"]
    backend:
      requires: ["shared"]

generator:
  templates:
    - "./templates"

telemetry: true