Skip to main content


A project is a library, application, package, binary, tool, etc, that contains source files, test files, assets, resources, and more. A project must exist and be configured within a workspace.


A project name (or identifier) is a unique resource for locating a project. The name is explicitly configured within .moon/workspace.yml, as a key within the projects setting, and can be written in camel/kebab/snake case. Names support a-z, A-Z, 0-9, _, -, /, and must start with a character.

Names are used heavily by configuration and the command line to link and reference everything. They're also a much easier concept for remembering projects than file system paths, and they typically can be written with less key strokes.

Lastly, a project name can be paired with a task name to create a target.


Aliases are a secondary approach for naming projects, and can be used as a drop-in replacement for standard names. What this means is that an alias can also be used when configuring dependencies, or defining targets.

However, the difference between aliases and names is that aliases can not be explicit configured in moon. Instead, they are specific to a project's primary programming language, and are inferred based on that context (when enabled in settings). For example, a JavaScript or TypeScript project will use the name field from its package.json as the alias.

Because of this, a project can either be reference by its name or alias, or both. Choose the pattern that makes the most sense for your company or team!


Projects can depend on other projects within the workspace to build a project graph, and in turn, a dependency graph for executing tasks. Project dependencies are divided into 2 categories:

  • Explicit dependencies - These are dependencies that are explicitly defined in a project's moon.yml config file, using the dependsOn setting. Explicit dependencies provide more built-in functionality than implicit, like project syncing.
  • Implicit dependencies - These are dependencies that are implicitly discovered by moon when scanning the repository. How an implicit dependency is discovered is based on the project's language setting, and how that language's ecosystem functions.


Projects can be configured with an optional moon.yml in the project root, or through the optional .moon/project.yml which applies to all projects.


A moon project does not require a package.json, but when one exists, the following functionality is enabled.

  • Dependency versions are included when computing cache keys and hashes.
  • Depended on projects (dependsOn) are mapped as workspace dependencies (when applicable).


A moon project does not require TypeScript or a tsconfig.json, but when one exists, the following functionality is enabled.

  • Depended on projects (dependsOn) are mapped as TypeScript project references (when applicable).

File name can be customized with the typescript.projectConfigFileName setting.