Skip to main content

moon.yml

The moon.yml configuration file (formerly project.yml in version <=0.9) is not required but can be used to define additional metadata for a project, override inherited tasks, and more at the project-level. When used, this file must exist in a project's root, as configured in projects.

dependsOnv0.9

(ProjectID | DependencyConfig)[]

Explicitly defines other projects that this project depends on, primarily when generating the project and task graphs. The most common use case for this is building those projects before building this one, and for syncing package.json dependencies and tsconfig.json project references when applicable.

When defined, this setting requires an array of project names, which are the keys found in the projects map.

moon.yml
dependsOn:
- 'apiClients'
- 'designSystem'

A dependency object can also be defined, where a specific scope can be assigned, which accepts "production" (default), "development", or "peer". This maps to the appropriate field in package.json when syncing.

moon.yml
dependsOn:
- id: 'apiClients'
scope: 'production'
- id: 'designSystem'
scope: 'peer'

Learn more about implicit and explicit dependencies.

fileGroups

Record<string, string[]>

Defines file groups to be used by local tasks. By default, this setting is not required for the following reasons:

  • File groups are an optional feature, and are designed for advanced use cases.
  • File groups defined in .moon/project.yml will be inherited by all projects.

When defined this setting requires a map, where the key is the file group name, and the value is a list of globs or paths. Globs and paths are relative to a project (even when defined globally).

moon.yml
fileGroups:
configs:
- '*.config.{js,cjs,mjs}'
- '*.json'
sources:
- 'src/**/*'
- 'types/**/*'
tests:
- 'tests/**/*'
- '**/__tests__/**/*'
assets:
- 'assets/**/*'
- 'images/**/*'
- 'static/**/*'
- '**/*.{scss,css}'

The code snippet above is merely an example of file groups. Feel free to use those groups as-is, modify the glob lists, add and remove groups, or implement completely new groups. The choice is yours!

languagev0.3

ProjectLanguage

The primary programming language the project is written in. Supports the following values:

  • bash - A Bash based project (Unix only).v0.6
  • batch - A Batch based project (Windows only). v0.9
  • javascript - A JavaScript based project. Inferred when package.json exists.
  • typescript - A TypeScript based project. Inferred when tsconfig.json exists.
  • unknown (default) - When not configured or inferred.
moon.yml
language: 'javascript'

For convenience, when this setting is not defined, moon will attempt to detect the language based on configuration files found in the project root.

project

ProjectMetadataConfig

The project setting defines metadata about the project itself. Although this setting is optional, when defined, all fields within it must be defined as well.

moon.yml
project:
name: 'moon'
description: 'A monorepo management tool.'
channel: '#moon'
owner: 'infra.platform'
maintainers: ['miles.johnson']

The information listed within project is purely informational and primarily displayed within the CLI. However, this setting exists for you, your team, and your company, as a means to identify and organize all projects. Feel free to build your own tooling around these settings!

channel

string

The Slack, Discord, Teams, IRC, etc channel name (with leading #) in which to discuss the project.

description

string

A description of what the project does and aims to achieve. Be as descriptive as possible, as this is the kind of information search engines would index on.

maintainers

string[]

A list of people/developers that maintain the project, review code changes, and can provide support. Can be a name, email, LDAP name, GitHub username, etc, the choice is yours.

name

string

A human readable name of the project. This is different from the unique project name configured in projects.

owner

string

The team or organization that owns the project. Can be a title, LDAP name, GitHub team, etc. We suggest not listing people/developers as the owner, use maintainers instead.

tasks

Record<string, TaskConfig>

Tasks are actions that are ran within the context of a project, and commonly wrap an npm binary or system command. This setting requires a map, where the key is a unique name for the task, and the value is an object of task parameters.

moon.yml
tasks:
format:
command: 'prettier'
lint:
command: 'eslint'
test:
command: 'jest'
typecheck:
command: 'tsc'

commandRequired

string | string[]

The command field is the command line to run for the task, including the command name (must be first) and any optional arguments. This field is required when not inheriting a global task of the same name.

moon.yml
tasks:
format:
# Using a string
command: 'prettier --check .'
# Using an array
command:
- 'prettier'
- '--check'
- '.'

By default a task assumes the command name is an npm binary, and if you'd like to reference a system command, you'll also need to set the type to "system". We do our best to automatically detect this, but it's not perfect.

moon.yml
tasks:
clean:
command: 'rm -rf ./dist'
type: 'system'

Special commands

For interoperability reasons, the following command names have special handling.

  • noop, no-op, nop - Marks the task as a "no operation". Will not execute a command in the action runner but can define dependencies.
  • When type is "node":
    • node, npm, pnpm, yarn - Uses the binaries from the toolchain.
  • When type is "system":
    • cmd, cmd.exe - Will execute the arguments with cmd.exe (Windows only).
    • powershell, powershell.exe - Will execute the arguments with powershell.exe (Windows only).

args

string | string[]

The args field is a collection of additional arguments to pass to the command line when executing the task. This field exists purely to provide arguments for inherited tasks.

This setting can be defined using a string, or an array of strings. We suggest using arrays when dealing with many args, or the args string cannot be parsed easily.

moon.yml
tasks:
test:
command: 'jest'
# Using a string
args: '--color --maxWorkers 3'
# Using an array
args:
- '--color'
- '--maxWorkers'
- '3'

However, for the array approach to work correctly, each argument must be its own distinct item, including argument values. For example:

moon.yml
tasks:
test:
command: 'jest'
args:
# Valid
- '--maxWorkers'
- '3'
# Also valid
- '--maxWorkers=3'
# Invalid
- '--maxWorkers 3'

deps

Target[]

The deps field is a list of other tasks (known as targets), either within this project or found in another project, that will be executed before this task. It achieves this by generating a directed task graph based on the project graph.

moon.yml
tasks:
build:
command: 'webpack'
deps:
- 'apiClients:build'
- 'designSystem:build'

env

Record<string, string>

The env field is map of strings that are passed as environment variables when running the command. Variables defined here will take precedence over those loaded with envFile.

moon.yml
tasks:
build:
command: 'webpack'
env:
NODE_ENV: 'production'

inputsv0.9

string[]

The inputs field is a list of sources that calculate whether to execute this task based on the environment and files that have been touched since the last time the task has been ran. If not defined, then all files within a project are considered an input (**/*).

Inputs support the following source types:

moon.yml
tasks:
lint:
command: 'eslint'
inputs:
# Config files anywhere within the project
- '**/.eslintignore'
- '**/.eslintrc.js'
# Config files at the workspace root
- '/.eslintignore'
- '/.eslintrc.js'
# Environment variables
- '$ESLINT_CACHE'
caution

When using an environment variable, we assume it's not defined by default, and will trigger an affected state when it is defined. If the environment variable always exists, then the task will always run and bypass the cache.

localv0.11

boolean

Marks the task as local only. This should primarily be enabled for long-running or never-ending tasks, like development servers and watch mode. Defaults to true if the task name is "dev", "start", or "serve", and false otherwise.

This is a convenience setting for local development that sets the following task options:

moon.yml
tasks:
dev:
command: 'webpack server'
local: true

outputs

string[]

The outputs field is a list of files and folders that are created as a result of executing this task, excluding internal cache files that are created from the underlying command (for example, .eslintcache).

Outputs are necessary for incremental caching and rehydration. If you'd prefer to avoid that functionality, omit this field.

moon.yml
tasks:
build:
command: 'webpack'
outputs:
# Relative from project root
- 'build/'

Outputs require project relative file patterns.

options

TaskOptionsConfig

The options field is an object of configurable options that can be used to modify the task and its execution. The following fields can be provided, with merge related fields supporting all merge strategies.

moon.yml
tasks:
typecheck:
command: 'tsc --noEmit'
options:
mergeArgs: 'replace'
runFromWorkspaceRoot: true

cachev0.9

boolean

Whether to cache the task's execution result using our smart hashing system. If disabled, will not create a cache hash, and will not persist a task's outputs. Defaults to true.

We suggest disabling caching when defining cleanup tasks, one-off scripts, or file system heavy operations.

moon.yml
tasks:
clean:
command: 'rm -rf ./temp'
options:
cache: false

envFilev0.11

boolean | string

A boolean or path to a project relative file (also know as dotenv file) that defines a collection of environment variables for the current task. Variables will be loaded on project creation, but will not override those defined in env.

moon.yml
tasks:
build:
command: 'webpack'
options:
# Defaults to .env
envFile: true
# Or
envFile: '.env.production'

mergeArgs

TaskMergeStrategy

The strategy to use when merging the args list with an inherited task. Defaults to "append".

mergeDeps

TaskMergeStrategy

The strategy to use when merging the deps list with an inherited task. Defaults to "append".

mergeEnv

TaskMergeStrategy

The strategy to use when merging the env map with an inherited task. Defaults to "append".

mergeInputs

TaskMergeStrategy

The strategy to use when merging the inputs list with an inherited task. Defaults to "append".

mergeOutputs

TaskMergeStrategy

The strategy to use when merging the outputs list with an inherited task. Defaults to "append".

outputStylev0.10

TaskOutputStyle

Controls how stdout/stderr is displayed when the task is ran as a transitive target. By default, this setting is not defined and defers to the action runner, but can be overridden with one of the following values:

  • buffer - Buffers output and displays after the task has exited (either success or failure).
  • buffer-only-failure - Like buffer, but only displays on failures.v0.11
  • hash - Ignores output and only displays the generated hash.v0.11
  • none - Ignores output. v0.11
  • stream - Streams output directly to the terminal. Will prefix each line of output with the target.
moon.yml
tasks:
test:
# ...
options:
outputStyle: 'stream'

retryCount

number

The number of attempts the task will retry execution before returning a failure. This is especially useful for flaky tasks. Defaults to 0.

moon.yml
tasks:
test:
# ...
options:
retryCount: 3

runDepsInParallelv0.10

boolean

Whether to run the task's deps in parallel or serial (in order). Defaults to true.

moon.yml
tasks:
start:
# ...
deps:
- '~:clean'
- '~:build'
options:
runDepsInParallel: false

runInCI

boolean

Whether to run the task automatically in a CI (continuous integration) environment when affected by touched files, typically through the moon ci command. Defaults to true unless the local setting is disabled, but is always true when a task defines outputs.

moon.yml
tasks:
build:
# ...
options:
runInCI: false

runFromWorkspaceRoot

boolean

Whether to use the workspace root as the working directory when executing a task. Defaults to false and runs from the task's project root.

moon.yml
tasks:
typecheck:
# ...
options:
runFromWorkspaceRoot: true

type

The type field defines the type of command to run, where to locate its executable, and which tool to execute it with. By default will set to a value based on the project's language.

  • node - Command is a binary within node modules and will be executed with Node.js.
  • system - Command is expected to exist within the system's environment.
  • unknown - When not inferred.
moon.yml
tasks:
env:
command: 'printenv'
type: 'system'

This field exists because of our toolchain, and moon ensuring the correct command is ran.

type

ProjectType

The type of project. Supports the following values:

  • application - A backend or frontend application that communicates over HTTP, TCP, RPC, etc.
  • library - A self-contained, shareable, and publishable set of code.
  • tool - An internal tool, command line program, one-off script, etc.
  • unknown (default) - When not configured.
moon.yml
type: 'application'

workspace

Dictates how a project interacts with settings defined at the workspace-level.

inheritedTasks

Provides a layer of control when inheriting tasks from .moon/project.yml.

exclude

string[]

The optional exclude setting permits a project to exclude specific tasks from being inherited. It accepts a list of strings, where each string is the name of a global task to exclude.

moon.yml
workspace:
inheritedTasks:
# Exclude the inherited `test` task for this project
exclude: ['test']

Exclusion is applied after inclusion and before renaming.

include

string[]

The optional include setting permits a project to only include specific inherited tasks (works like an allow/white list). It accepts a list of strings, where each string is the name of a global task to include.

When this field is not defined, the project will inherit all tasks from the global project config.

moon.yml
workspace:
inheritedTasks:
# Include *no* tasks (works like a full exclude)
include: []

# Only include the `lint` and `test` tasks for this project
include:
- 'lint'
- 'test'

Inclusion is applied before exclusion and renaming.

rename

Record<string, string>

The optional rename setting permits a project to rename the inherited task within the current project. It accepts a map of strings, where the key is the original name (found in the global project config), and the value is the new name to use.

For example, say we have 2 tasks in the global project config called buildPackage and buildApplication, but we only need 1, and since we're an application, we should omit and rename.

moon.yml
workspace:
inheritedTasks:
exclude: ['buildPackage']
rename:
buildApplication: 'build'

Renaming occurs after inclusion and exclusion.

typescriptv0.12

boolean

Enables or disables TypeScript support for this specific project. Currently controls project reference syncing and tsconfig.json creation. Defaults to true.

moon.yml
workspace:
typescript: false