Project Configuration

The moon.* configuration file defines project-level settings, metadata, tasks, and dependencies. This file is optional but recommended for customizing project behavior.

Configuration File

Location: <project-root>/moon.yml or <project-root>/moon.json Type: ProjectConfig

Schema

Project Identity

string

Overrides the project identifier from the workspace projects setting.

id: 'custom-id'

_{Added in v1.18.0}

language

LanguageType

default:"unknown"

The primary programming language. Supports: bash, batch, go, javascript, php, python, ruby, rust, typescript, unknown, or custom values.

language: 'typescript'

If not defined, moon attempts to detect the language from configuration files.

layer

LayerType

default:"unknown"

The layer within a stack. Supports: application, automation, configuration, library, scaffolding, tool, unknown.

layer: 'library'

Used for task inheritance and constraint enforcement.

stack

StackType

default:"unknown"

The technology stack. Supports: backend, data, frontend, infrastructure, systems, unknown.

stack: 'frontend'

_{Added in v1.22.0}

Project Metadata

project

ProjectMetadataConfig

Expanded information about the project.

Show properties

title

string

Human-readable project name.

description

string

required

Description of the project’s purpose.

owner

string

Team or organization that owns the project.

maintainers

string[]

Individual maintainers of the project.

channel

string

Communication channel (must start with #).

project:
  channel: '#engineering'

Custom metadata fields are also supported:

project:
  title: 'Web Application'
  description: 'Customer-facing web app'
  deprecated: true
  team: 'platform'

_{Custom fields added in v2.0.0}

Dependencies

dependsOn

ProjectDependsOn[]

Other projects that this project depends on. Supports string IDs or objects with scope.

# Simple format
dependsOn:
  - 'design-system'
  - 'api-client'

# Advanced format
dependsOn:
  - id: 'design-system'
    scope: 'production'
  - id: 'test-utils'
    scope: 'development'

Scopes: production (default), development, build, peer

Code Ownership

owners

OwnersConfig

Defines ownership of source code within the project.

Show properties

defaultOwner

string

Default owner for all paths.

owners:
  defaultOwner: '@frontend'

paths

string[] | object

Maps file paths to owners. Supports list or object format.

# List format (uses defaultOwner)
owners:
  defaultOwner: '@team'
  paths:
    - 'src/**/*'
    - 'tests/**/*'

# Object format (specific owners)
owners:
  paths:
    '**/*.ts': ['@frontend']
    '**/*.rs': ['@backend']
    'docs/': ['@docs', '@frontend']

requiredApprovals

number

default:1

Required approvals for pull/merge requests (Bitbucket/GitLab only).

optional

boolean

default:false

Marks code owners section as optional (GitLab only).

customGroups

object

Custom groups for Bitbucket Code Owners app.

owners:
  customGroups:
    '@@@backend': ['@user', '@@team']

_{Added in v1.8.0}

Tasks

tasks

object

Map of task identifiers to task configurations.

tasks:
  build:
    command: 'vite build'
    inputs:
      - 'src/**/*'
    outputs:
      - 'dist'
  
  test:
    command: 'vitest'
    deps:
      - '~:build'

See Tasks Configuration for complete task schema.

fileGroups

object

Maps file group IDs to lists of globs, paths, or environment variables.

fileGroups:
  sources:
    - 'src/**/*'
    - 'types/**/*'
  configs:
    - '*.config.{js,ts}'
    - '*.json'
  tests:
    - 'tests/**/*'
    - '**/__tests__/**/*'

Reference in tasks using token functions:

tasks:
  lint:
    inputs:
      - '@group(sources)'
      - '@group(configs)'

env

object

Environment variables inherited by all tasks in the project.

env:
  NODE_ENV: 'production'
  API_URL: 'https://api.example.com'

Supports substitution:

env:
  APP_TARGET: '${REGION}-${ENVIRONMENT}'

Docker Integration

docker

ProjectDockerConfig

Docker integration settings for the project.

Show properties

file

object

Dockerfile generation configuration.

Show properties

buildTask

string

Task to run for building before starting.

docker:
  file:
    buildTask: 'build'

startTask

string

Task to run when starting (used as CMD).

image

string

Base Docker image. Defaults to toolchain-based image.

runPrune

boolean

default:true

Run moon docker prune after building._{Added in v2.0.0}

runSetup

boolean

default:true

Run moon docker setup after scaffolding._{Added in v2.0.0}

template

string

Custom Dockerfile template path (Tera powered)._{Added in v2.0.0}

scaffold

object

Scaffolding configuration.

Show properties

configsPhaseGlobs

string[]

default:["**/*"]

Globs for copying files to configs skeleton.

sourcesPhaseGlobs

string[]

default:["**/*"]

Globs for copying files to sources skeleton.

_{Added in v1.27.0}

Toolchain Overrides

toolchains

ProjectToolchainsConfig

Overrides workspace-level toolchain settings.

Show properties

default

string

Default toolchain for all tasks in this project.

toolchains:
  default: 'node'

_{Added in v1.31.0}

[toolchain]

object

Toolchain-specific overrides (e.g., node, rust, bun).

toolchains:
  node:
    version: '20.0.0'
  typescript:
    syncProjectReferences: false

_{Added in v2.0.0}

Workspace Overrides

workspace

ProjectWorkspaceConfig

Overrides workspace-level settings for this project.

Show properties

inheritedTasks

object

Controls which inherited tasks are included or excluded.

workspace:
  inheritedTasks:
    exclude: ['lint', 'format']
    include: ['build', 'test']
    rename:
      test: 'test-unit'

Complete Example

apps/web/moon.yml

id: 'web-app'
language: 'typescript'
stack: 'frontend'
layer: 'application'
tags:
  - 'react'
  - 'vite'

project:
  title: 'Web Application'
  description: 'Customer-facing web application'
  owner: '@frontend-team'
  maintainers:
    - '[email protected]'
    - '[email protected]'
  channel: '#frontend'

dependsOn:
  - id: 'design-system'
    scope: 'production'
  - id: 'api-client'
    scope: 'production'

owners:
  defaultOwner: '@frontend'
  paths:
    '**/*.tsx': ['@frontend', '@ui-team']
    'src/api/': ['@backend']

fileGroups:
  sources:
    - 'src/**/*'
    - 'index.html'
  configs:
    - '*.config.{js,ts}'
    - 'tsconfig.json'

env:
  NODE_ENV: 'production'
  VITE_API_URL: '${API_BASE_URL}'

tasks:
  dev:
    command: 'vite'
    preset: 'server'
  
  build:
    command: 'vite build'
    inputs:
      - '@group(sources)'
      - '@group(configs)'
    outputs:
      - 'dist'
    deps:
      - 'design-system:build'
  
  test:
    command: 'vitest'
    deps:
      - '~:build'
  
  preview:
    command: 'vite preview'
    deps:
      - '~:build'

docker:
  file:
    buildTask: 'build'
    startTask: 'preview'
    image: 'node:20-alpine'

toolchains:
  default: 'node'
  node:
    version: '20.0.0'

Configuration Schemas

Project Configuration

Configuration File

Schema

Project Identity

Project Metadata

Dependencies

Code Ownership

Tasks

Docker Integration

Toolchain Overrides

Workspace Overrides

Complete Example

Build docs developers (and LLMs) love

Configuration Schemas

​Configuration File

​Schema

​Project Identity

​Project Metadata

​Dependencies

​Code Ownership

​Tasks

​Docker Integration

​Toolchain Overrides

​Workspace Overrides

​Complete Example

​Related

Build docs developers (and LLMs) love

Configuration File

Schema

Project Identity

Project Metadata

Dependencies

Code Ownership

Tasks

Docker Integration

Toolchain Overrides

Workspace Overrides

Complete Example

Related