moon.yml configuration file 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
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
tsconfig.json project references when
When defined, this setting requires an array of project names, which are the keys found in the
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.
- id: 'apiClients'
- id: 'designSystem'
Learn more about implicit and explicit dependencies.
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
go- A Go based project.v0.21
php- A PHP based project.v0.21
python- A Python based project.v0.21
ruby- A Ruby based project.v0.21
rust- A Rust based project.v0.21
typescript- A TypeScript based project.
unknown(default) - When not configured or inferred.
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 setting defines metadata about the project itself.
description: 'A monorepo management tool.'
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!
The Slack, Discord, Teams, IRC, etc channel name (with leading #) in which to discuss the project.
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.
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.
A human readable name of the project. This is different from the unique project name configured in
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.
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.
env field is map of strings that are passed as environment variables to all tasks within the
current project. Project-level variables will not override task-level variables of the same name.
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/tasks.ymlwill be inherited by all projects.
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!
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.
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.
# Using a string
command: 'prettier --check .'
# Using an array
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
platform to "system". We do our best to
automatically detect this, but it's not accurate in all scenarios.
command: 'rm -rf ./dist'
For interoperability reasons, the following command names have special handling.
nop- Marks the task as a "no operation". Will not execute a command in the action pipeline but can define dependencies.
yarn- Uses the binaries from the toolchain.
cmd.exe- Will execute the arguments with
powershell.exe- Will execute the arguments with
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
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.
# Using a string
args: '--color --maxWorkers 3'
# Using an array
However, for the array approach to work correctly, each argument must be its own distinct item, including argument values. For example:
# Also valid
- '--maxWorkers 3'
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.
# A task within the current project
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
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:
- Environment variables (must start with a
- Files, folders, globs (project and workspace relative file patterns)
# Config files anywhere within the project
# Config files at the workspace root
# Environment variables
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.
When using globs, be aware that files that match the glob, but are ignored via
similar), will not be considered an input. To work around this, use explicit file inputs.
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
This is a convenience setting for local development that sets the following task options:
command: 'webpack server'
outputs field is a list of files and folders (using
project relative file patterns) that are created as a
result of executing this task, typically from a build or compilation related task. Outputs are
necessary for incremental caching and hydration. If you'd prefer to avoid that
functionality, omit this field.
# Relative from project root
Globs can also be used if you'd like to restrict which files are cached. For example, when building
.js files, but exclude
.map and other files.
When using globs and moon hydrates an output (a cache hit), all files not matching the glob will be deleted. Ensure that all files critical for the build to function correctly are included.
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
command: 'tsc --noEmit'
When enabled and the
--affected option is
provided, all affected files that match this task's
inputs will be passed as relative
file paths as command line arguments, and as a
MOON_AFFECTED_FILES environment variable. If there
are no affected files,
. (current directory) will be passed instead for arguments, and an empty
value for the environment variable.
# Only pass args
# Only set env var
When using this option, ensure that explicit files or
. are not present in the
list. Furthermore, this functionality will only work if the task's command supports an arbitrary
list of files being passed as arguments.
We suggest disabling caching when defining cleanup tasks, one-off scripts, or file system heavy operations.
command: 'rm -rf ./temp'
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
# Defaults to .env
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 pipeline, 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, 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.
The number of attempts the task will retry execution before returning a failure. This is especially
useful for flaky tasks. Defaults to
Whether to run the task's
deps in parallel or serial (in order). Defaults to
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
local setting is disabled, but is always true when a task defines
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.
platform field defines the platform the command runs on, where to locate its executable, and
which tool to execute it with. By default moon will set to a value based on the project's
node- Command is a binary within
node_modulesand will be executed with Node.js.
system- Command is expected to exist within the system's environment / user's shell.
unknown- When not configured or inferred.
This field exists because of our toolchain, and moon ensuring the correct command is ran.
Dictates how a project interacts with settings defined at the top-level.
Configures Node.js for this project and overrides the top-level
Currently, only the Node.js version can be overridden per-project, not the package manager.
Defines the explicit Node.js version to use when running tasks for this project.
Enables or disables TypeScript support for this project. Currently
controls project reference syncing and
tsconfig.json creation. Defaults to
Provides a layer of control when inheriting tasks from
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.
# Exclude the inherited `test` task for this project
Exclusion is applied after inclusion and before renaming.
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.
# Include *no* tasks (works like a full exclude)
# Only include the `lint` and `test` tasks for this project
Inclusion is applied before exclusion and renaming.
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
buildApplication, but we only need 1, and since we're an application, we should omit and rename.
Renaming occurs after inclusion and exclusion.