Project Configuration

Complete API reference for the moon.* project configuration schema

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

id · 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}

tags · string[]

Tags for categorizing, querying, and task inheritance.

tags:
  - 'react'
  - 'typescript'

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:
    - '[e-mail]'
    - '[e-mail]'
  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'

Related

• Project Concepts
• Task Configuration
• Workspace Configuration
• Toolchain Configuration