.moon/workspace.yml

The .moon/workspace.yml file configures available projects and their locations, the toolchain, and the workspace development environment.

extendsv0.4

string

Defines an external .moon/workspace.yml to extend and inherit settings from. Perfect for reusability and sharing configuration across repositories and projects. When defined, this setting must be an HTTPS URL or relative file system path that points to a valid YAML document!

.moon/workspace.yml

extends: 'https://raw.githubusercontent.com/organization/repository/master/.moon/workspace.yml'

caution

Settings will be merged recursively for blocks, with values defined in the local configuration taking precedence over those defined in the extended configuration. However, the projects setting does not merge!

projectsRequired

Record<string, string> | string[]

Defines the location of all projects within the workspace. Supports either a manual map of projects (default), or a list of globs in which to automatically locate projects.

Manual

When using a map, each project must be manually configured and requires a unique name as the map key, where this name is used heavily on the command line and within the project graph for uniquely identifying the project amongst all projects. The map value (known as the project source) is a file system path to the project folder, relative from the workspace root, and must be contained within the workspace boundary.

.moon/workspace.yml

projects:
  admin: 'apps/admin'
  apiClients: 'packages/api-clients'
  designSystem: 'packages/design-system'
  web: 'apps/web'

Automatic

If manually mapping projects is too tedious or cumbersome, you may provide a list of globs to automatically locate all project folders, relative from the workspace root.

When using this approach, the project name is derived from the project folder name, and is cleaned to our supported characters . Furthermore, globbing does risk the chance of collision, and when that happens, we log a warning and skip the conflicting project from being configured in the project graph.

.moon/workspace.yml

projects:
  - 'apps/*'
  - 'packages/*'

Unlike packages in the JavaScript ecosystem, a moon project does not require a package.json, and is not coupled to Yarn workspaces (or similar architectures).

Languages

node

NodeConfig

Defines the Node.js version and package manager to install within the toolchain, as moon does not use a Node.js binary found on the local machine. Managing the Node.js version within the toolchain ensures a deterministic environment across any machine (whether a developer, CI, or production machine).

version

string

Defines the explicit Node.js version to use. We require an explicit and semantic major, minor, and patch version, to ensure the same environment is used across every machine. Ranges are not supported.

.moon/workspace.yml

node:
  version: '16.13.0'

Version can be overridden with the MOON_NODE_VERSION environment variable.

packageManager

npm | pnpm | yarn

Defines which package manager to utilize within the workspace. Supports npm (default), pnpm, or yarn.

.moon/workspace.yml

node:
  packageManager: 'yarn'

npm, pnpm, yarn

PackageManagerConfig

Optional fields for defining package manager specific configuration. The chosen setting is dependent on the value of node.packageManager. If these settings are not defined, the latest version of the active package manager will be used (when applicable).

version

string

The version setting defines the explicit package manager version to use. We require an explicit major, minor, and patch version, to ensure the same environment is used across every machine.

.moon/workspace.yml

node:
  packageManager: 'yarn'
  yarn:
    version: '3.1.0'

Version can be overridden with the MOON_NPM_VERSION, MOON_PNPM_VERSION, or MOON_YARN_VERSION environment variables.

yarn

plugins

string[]

A list of plugins that will automatically be imported using yarn plugin import (Yarn 2+ only). For performance reasons, plugins will only be imported when the Yarn version changes.

.moon/workspace.yml

node:
  packageManager: 'yarn'
  yarn:
    version: '3.1.0'
    plugins:
      - 'interactive-tools'
      - 'workspace-tools'

addEnginesConstraint

boolean

Injects the currently configured Node.js version as an engines constraint to the root package.json field. Defaults to true.

node:
  addEnginesConstraint: true

For example, say our Node.js version is "16.15.0", and when we execute a run process through the moon binary, it will update the root package.json with the below. We pin a fixed version to ensure other Node.js processes outside of our toolchain are utilizing the same version.

package.json

{
  // ...
  "engines": {
    "node": "16.15.0"
  }
}

aliasPackageNamesv0.10

NodeProjectAliasFormat

When enabled, will assign aliases to configured projects based on the name field in the project's package.json. Aliases can be used as a substitute for project names, allowing for the familiar package name to be used within targets or configuration.

This setting accepts one of the following values, which determines how to parse and assign the alias.

• name-and-scope - Will use the package name as-is, including any scope. For example, @scope/example or example.
• name-only - Will only use the name and disregard any scope. For example, @scope/example will become example.

.moon/workspace.yml

node:
  aliasPackageNames: 'name-only'

caution

This setting will eager load all package.jsons within the repository, which may result in reduced performance for a large amount of projects.

dedupeOnLockfileChange

boolean

Will dedupe dependencies after they have been installed, added, removing, or changed in any way, in an effort to keep the workspace tree as clean and lean as possible. Defaults to true.

.moon/workspace.yml

node:
  dedupeOnLockfileChange: true

dependencyVersionFormatv0.9

NodeVersionFormat

When syncing project dependencies, customize the format that will be used for the dependency version range. The following formats are supported (but use the one most applicable to your chosen package manager):

• file - Uses file:../relative/path and copies package contents.
• link - Uses link:../relative/path and symlinks package contents.
• star - Uses an explicit *.
• version - Uses the explicit version from the dependent project's package.json, e.g., "1.2.3".
• version-caret - Uses the version from the dependent project's package.json as a caret range, e.g., "^1.2.3".
• version-tilde - Uses the version from the dependent project's package.json as a tilde range, e.g., "~1.2.3".
• workspace (default) - Uses workspace:*, which resolves to "1.2.3". Requires package workspaces.
• workspace-caret - Uses workspace:^, which resolves to "^1.2.3". Requires package workspaces.
• workspace-tilde - Uses workspace:~, which resolves to "~1.2.3". Requires package workspaces.

.moon/workspace.yml

node:
  dependencyVersionFormat: 'link'

This setting does not apply to peer dependencies, as they will always use a format of ^<major>.0.0.

inferTasksFromScriptsv0.8

boolean

Will infer and automatically create tasks from package.json scripts. Defaults to false.

This requires the project's language to be "javascript" or "typescript", a package.json to exist in the project, and will take the following into account:

• Script names will be converted to kebab-case, and will become the task ID.
• Pre, post, and life cycle hooks are ignored.
• Tasks defined in .moon/project.yml or moon.yml take precedence over scripts of the same name.

To verify inferred tasks, run moon project <id> (pass --json to view raw config and options). Tasks that are inferred will have their command and args set to moon node run-script.

.moon/workspace.yml

node:
  inferTasksFromScripts: true

caution

This implementation shares functionality with moon migrate from-package-json, and will attempt to determine environment variables, outputs, CI options, and more! Be aware of these when utilizing this feature, especially in regards to runInCI, as it may be inaccurate!

syncProjectWorkspaceDependencies

boolean

Will sync a project's dependsOn setting as normal dependencies within the project's package.json. If a dependent project does not have a package.json, or if a dependency of the same name has an explicit version already defined, the sync will be skipped. Defaults to true.

.moon/workspace.yml

node:
  syncProjectWorkspaceDependencies: true

A quick example on how this works. Given the following dependsOn:

moon.yml

dependsOn:
  - 'designSystem'
  - 'reactHooks'

Would result in the following dependencies within a project's package.json. The version format can be customized with node.dependencyVersionFormat.

package.json

{
  // ...
  "dependencies": {
    "@company/design-system": "workspace:*",
    "@company/react-hooks": "workspace:*"
    // ...
  }
}

syncVersionManagerConfig

(none) | nodenv | nvm

Will sync the currently configured Node.js version to a 3rd-party version manager's config/rc file. Supports "nodenv" (syncs to .node-version), "nvm" (syncs to .nvmrc), or none (default).

.moon/workspace.yml

node:
  syncVersionManagerConfig: 'nvm'

This is a special setting that ensure other Node.js processes outside of our toolchain are utilizing the same version, which is a very common practice when managing dependencies.

typescriptv0.12

TypeScriptConfig

Dictates how moon interacts with and utilizes TypeScript within the workspace. This field is optional and is undefined by default. Define it to enable TypeScript support.

createMissingConfigv0.6

boolean

When syncing project references and a depended on project does not have a tsconfig.json, automatically create one. Defaults to true.

.moon/workspace.yml

typescript:
  createMissingConfig: true

projectConfigFileName

string

Defines the file name of the tsconfig.json found in the project root. We utilize this setting when syncing project references between projects. Defaults to tsconfig.json.

.moon/workspace.yml

typescript:
  projectConfigFileName: 'tsconfig.build.json'

rootConfigFileName

string

Defines the file name of the tsconfig.json found in the workspace root. We utilize this setting when syncing projects as references. Defaults to tsconfig.json.

.moon/workspace.yml

typescript:
  rootConfigFileName: 'tsconfig.projects.json'

rootOptionsConfigFileNamev0.6

string

Defines the file name of the config file found in the workspace root that houses shared compiler options. Defaults to tsconfig.options.json. This setting is used in the following scenarios:

• When creating a tsconfig.json for a project, sets the extends field to this value.

.moon/workspace.yml

typescript:
  rootOptionsConfigFileName: 'tsconfig.base.json'

syncProjectReferences

boolean

Will sync a project's dependsOn setting as project references within that project's tsconfig.json, and the workspace root tsconfig.json. Defaults to true when the parent typescript setting is defined, otherwise false.

.moon/workspace.yml

typescript:
  syncProjectReferences: true

A quick example on how this works. Given the following dependsOn:

dependsOn:
  - 'designSystem'
  - 'reactHooks'

Would result in the following references within both tsconfig.jsons.

tsconfig.json

{
  // ...
  "references": [
    // ...
    { "path": "../../design-system" },
    { "path": "../../react-hooks" }
  ]
}

Features

generatorv0.14

GeneratorConfig

Configures aspects of the template generator.

templates

string[]

A list of file system paths where templates can be located, relative from the workspace root. Defaults to ./templates.

.moon/workspace.yml

generator:
  templates:
    - './templates'
    - './other/templates'

hasherv0.13

HasherConfig

Configures aspects of smart hashing layer.

optimization

Determines the optimization level to utilize when hashing content before running targets.

• accuracy (default) - When hashing dependency versions, utilize the resolved value in the lockfile. This requires parsing the lockfile, which may reduce performance.
• performance - When hashing dependency versions, utilize the value defined in the manifest. This is typically a version range or requirement.

.moon/workspace.yml

hasher:
  optimization: 'performance'

runnerv0.13

RunnerConfig

Configures aspects of the action runner.

cacheLifetimev0.11

string

The maximum lifetime of cached artifacts before they're marked as stale and automatically removed by the action runner. Defaults to "7 days". This field requires an integer and a timeframe unit that can be parsed as a duration.

.moon/workspace.yml

runner:
  cacheLifetime: '24 hours'

implicitInputsv0.9

string[]

Defines task inputs that are implicit inherited by all tasks within the workspace. This is extremely useful for the "changes to these files should always trigger a task" scenario.

Like inputs, file paths/globs defined here are relative from the inheriting project. Project and workspace relative file patterns are supported and encouraged.

.moon/workspace.yml

runner:
  implicitInputs:
    - 'package.json'
    - '/.moon/project.yml'
    - '/.moon/workspace.yml'

When not defined, this setting defaults to the list in the example above. When this setting is defined, that list will be overwritten, so be sure to explicitly define them if you would like to retain that functionality.

inheritColorsForPipedTasksv0.3

boolean

Force colors to be inherited from the current terminal for all tasks that are ran as a child process and their output is piped to the action runner. Defaults to true. View more about color handling in moon.

.moon/workspace.yml

runner:
  inheritColorsForPipedTasks: true

logRunningCommandv0.4

boolean

When enabled, will log the task's command, resolved arguments, and working directory when a target is ran. Defaults to false.

.moon/workspace.yml

runner:
  logRunningCommand: true

vcs

VcsConfig

Configures the version control system to utilize within the workspace (and repository). A VCS is required for determining touched (added, modified, etc) files, calculating file hashes, computing affected files, and much more.

manager

git | svn

Defines the VCS tool/binary that is being used for managing the repository. Accepts "git" (default) or "svn" (experimental).

.moon/workspace.yml

vcs:
  manager: 'git'

defaultBranch

Defines the default upstream branch (master/main/trunk) in the repository for comparing differences against. For git, this is typically "master" (default) or "main", and must include the remote prefix (before /). For svn, this should always be "trunk".

.moon/workspace.yml

vcs:
  defaultBranch: 'master'