Skip to main content

.moon/toolchain.yml

v0.20

The .moon/toolchain.yml file configures the toolchain and the workspace development environment. This file is optional.

Managing tool version's within the toolchain ensures a deterministic environment across any machine (whether a developer, CI, or production machine).

.moon/toolchain.yml
$schema: 'https://moonrepo.dev/schemas/toolchain.json'

extends​

Defines an external .moon/toolchain.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/toolchain.yml
extends: 'https://raw.githubusercontent.com/organization/repository/master/.moon/toolchain.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.

node​

Defines the Node.js version and package manager to install within the toolchain.

version​

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/toolchain.yml
node:
  version: '16.13.0'

Version can be overridden with the MOON_NODE_VERSION environment variable.

packageManager​

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

.moon/toolchain.yml
node:
  packageManager: 'yarn'

npm, pnpm, yarn​

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​

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/toolchain.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​

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/toolchain.yml
node:
  packageManager: 'yarn'
  yarn:
    version: '3.1.0'
    plugins:
      - 'interactive-tools'
      - 'workspace-tools'

addEnginesConstraint​

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​

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/toolchain.yml
node:
  aliasPackageNames: 'name-only'

binExecArgs​

Additional command line arguments to pass to the node binary when it's being executed by running a target. This will apply arguments to all Node.js based targets, and cannot be changed on a per target basis.

.moon/toolchain.yml
node:
  binExecArgs:
    - '--preserve-symlinks'
    - '--loader'
    - '@boost/module/loader'

dedupeOnLockfileChange​

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/toolchain.yml
node:
  dedupeOnLockfileChange: true

dependencyVersionFormatv0.9​

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/toolchain.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​

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/tasks.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/toolchain.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​

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/toolchain.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​

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/toolchain.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​

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​

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

.moon/toolchain.yml
typescript:
  createMissingConfig: true

projectConfigFileName​

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/toolchain.yml
typescript:
  projectConfigFileName: 'tsconfig.build.json'

rootConfigFileName​

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/toolchain.yml
typescript:
  rootConfigFileName: 'tsconfig.projects.json'

rootOptionsConfigFileNamev0.6​

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:

.moon/toolchain.yml
typescript:
  rootOptionsConfigFileName: 'tsconfig.base.json'

routeOutDirToCache​

Updates the outDir compiler option in each project's tsconfig.json to route to moon's cache folder. This is useful when using project references and wanting to keep all the compiled .d.ts files out of the project folder. Defaults to false.

.moon/toolchain.yml
typescript:
  routeOutDirToCache: true

As a demonstration, if we had an npm package located at "packages/components", the outDir compiler option will be re-routed to the following when syncing.

<project>/tsconfig.json
{
  // ...
  "compilerOptions": {
    // ...
    "outDir": "../../.moon/cache/types/packages/components"
  }
}

syncProjectReferences​

Will sync a project's dependencies (when applicable) 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/toolchain.yml
typescript:
  syncProjectReferences: true

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

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

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

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

syncProjectReferencesToPaths​

Will sync a project's tsconfig.json project references to the paths compiler option, using the referenced project's package.json name. This is useful for mapping import aliases to their source code. Defaults to false.

.moon/toolchain.yml
typescript:
  syncProjectReferencesToPaths: true

As a demonstration, if we had a reference to a shared npm package with the name @brand/components, the paths compiler option would be updated to the following when syncing. The index file may exist in a src folder, or the root of the package.

<project>/tsconfig.json
{
  // ...
  "compilerOptions": {
    // ...
    "paths": {
      "@brand/components": ["../shared/components/src/index.ts"],
      "@brand/components/*": ["../shared/components/src/*"]
    }
  },
  "references": [
    {
      "path": "../shared/components"
    }
  ]
}

This setting runs after syncProjectReferences and will inherit any synced references from that setting.