Skip to main content

Toolchain

The toolchain is an internal layer for downloading, installing, and managing tools (languages, dependency managers, libraries, and binaries) that are required at runtime. We embrace this approach over relying on these tools "existing" in the current environment, as it ensures the following across any environment or machine:

  • The version and enabled features of a tool are identical.
  • Tools are isolated and unaffected by external sources.
  • Builds are consistent, reproducible, and hopefully deterministic.

Furthermore, this avoids a developer, pipeline, machine, etc, having to pre-install all the necessary tools, and to keep them in sync as time passes.

How it works

The toolchain is a .moon directory within the current user's home directory, e.g., ~/.moon.

The first step in a tool's life-cycle is being downloaded to ~/.moon/temp. Downloads are typically an archive that can be unpacked into a target directory.

Once downloaded, we verify the downloaded file by running a sha256 checksum. If this check fails for any reason, the toolchain is unusable, and the process is aborted.

After a successful verification, the last step in the tool's life-cycle can begin, installation. Depending on the type of download, the installation process may differ. For archives, we unpack the tool to ~/.moon/tools/<name>/<version>.

Configuration

The tools that are managed by the toolchain are configured through the .moon/toolchain.yml file, but can be overridden in each project with moon.yml.

Supported tools

The following tools will be managed by the toolchain.

Although the toolchain was designed for JavaScript projects, mainly powered by Node.js tooling, we will support other languages in the future when deemed necessary, like Ruby or Python.

Node.js

Since moon was designed for JavaScript based repo's, we intentionally support Node.js as a first-class citizen within the toolchain. Because of this, Node.js is always enabled.

  • Configured with: node
  • Installed to: ~/.moon/tools/node/x.x.x

npm

The npm binary comes pre-installed with Node.js, and will always exist, regardless of the node.packageManager setting.

  • Configured with: node.npm
  • Installed to: ~/.moon/tools/npm/x.x.x

pnpm

The pnpm library can be used as an alternative package manager to npm, and will be enabled when node.packageManager is set to "pnpm". The binary will be installed as a toolchain global npm dependency.

  • Configured with: node.pnpm
  • Installed to: ~/.moon/tools/pnpm/x.x.x

yarn

The yarn library can be used as an alternative package manager to npm, and will be enabled when node.packageManager is set to "yarn". The binary will be installed as a toolchain global npm dependency.

  • Configured with: node.yarn
  • Installed to: ~/.moon/tools/yarn/x.x.x

Supports v1 and v2/v3 (only node-modules linker mode currently).