Toolchain Configuration

The .moon/toolchains.* configuration file defines toolchain versions and settings for your workspace. Toolchains are language/tool environments managed by moon through proto.

Configuration File

Location: .moon/toolchains.yml or .moon/toolchains.json Type: ToolchainsConfig Optional: This file is optional. Toolchains can be configured or auto-detected.

Schema

Core Settings

extends

string | string[]

Extends one or many toolchain configuration files. Supports relative paths or HTTPS URLs.

extends: 'https://example.com/.moon/toolchains.yml'

Settings merge recursively with local configuration taking precedence._{Added in v1.12.0}

Moon Configuration

moon

MoonConfig

Configures moon release information and downloads.

Show properties

manifestUrl

string

HTTPS URL to fetch version information from.

moon:
  manifestUrl: 'https://proxy.corp.net/moon/version'

downloadUrl

string

HTTPS URL to download moon binaries from.Defaults to: https://github.com/moonrepo/moon/releases

moon:
  downloadUrl: 'https://github.com/moonrepo/moon/releases/latest/download'

_{Added in v1.29.0}

Proto Configuration

proto

ProtoConfig

Configures moon’s integration with proto.

Show properties

version

string

Version of proto to install and use. If not installed, will be auto-installed.

proto:
  version: '0.51.0'

_{Added in v1.39.0}

Toolchain Plugins

Toolchains are configured as top-level keys using their identifier. Each toolchain is a WASM plugin managed by proto.

[toolchain]

ToolchainPluginConfig

Configuration for a specific toolchain.

Show properties

version

string

Version to install and use. Supports:

Specific versions: 1.2.3
Version ranges: ^1.2.0, ~1.2.3
Aliases: latest, stable
Partial versions: 1.2, 1

node:
  version: '20.0.0'
rust:
  version: '^1.70'

versionFromPrototools

boolean | string

default:true

Inherit version from root .prototools file.

true: Use same identifier
false: Don’t inherit
"custom-id": Use different identifier

node:
  versionFromPrototools: true
unstable_python:
  versionFromPrototools: 'python'

plugin

string

WASM plugin locator. Accepts file paths and URLs.Built-in toolchains auto-configure this. Required for custom toolchains.

custom:
  plugin: 'https://example.com/plugin.wasm'
  version: '1.0.0'

config

object

Arbitrary configuration passed to the WASM plugin.Configuration options vary by toolchain. Check plugin documentation.

node:
  version: '20.0.0'
  config:
    bundledNpm: true

Built-in Toolchains

moon provides built-in support for common language toolchains:

JavaScript Ecosystem

javascript

ToolchainPluginConfig

JavaScript language support. Required for other JavaScript toolchains.

javascript:
  version: 'latest'

Run moon toolchain info javascript for available settings.

node

ToolchainPluginConfig

Node.js runtime. Requires javascript toolchain.

node:
  version: '20.0.0'
  config:
    bundledNpm: true

Run moon toolchain info node for available settings.

bun

ToolchainPluginConfig

Bun runtime. Requires javascript toolchain.

bun:
  version: 'latest'

Run moon toolchain info bun for available settings.

deno

ToolchainPluginConfig

Deno runtime. Requires javascript toolchain.

deno:
  version: '1.40.0'

Run moon toolchain info deno for available settings.

typescript

ToolchainPluginConfig

TypeScript compiler.

typescript:
  version: '5.0.0'

Run moon toolchain info typescript for available settings.

Package Managers

npm

ToolchainPluginConfig

npm package manager. Requires node toolchain.

npm:
  version: '10.0.0'

Run moon toolchain info npm for available settings.

pnpm

ToolchainPluginConfig

pnpm package manager. Requires node toolchain.

pnpm:
  version: '8.0.0'

Run moon toolchain info pnpm for available settings.

yarn

ToolchainPluginConfig

Yarn package manager. Requires node toolchain.

yarn:
  version: '4.0.0'

Run moon toolchain info yarn for available settings.

Other Languages

ToolchainPluginConfig

Go language toolchain.

go:
  version: '1.21.0'

Run moon toolchain info go for available settings.

rust

ToolchainPluginConfig

Rust language toolchain.

rust:
  version: '1.75.0'

Run moon toolchain info rust for available settings.

unstable_python

ToolchainPluginConfig

Python language toolchain (experimental).

unstable_python:
  version: '3.12.0'

Run moon toolchain info unstable_python for available settings.

unstable_pip

ToolchainPluginConfig

pip package manager (experimental). Requires unstable_python.

unstable_pip:
  version: 'latest'

Run moon toolchain info unstable_pip for available settings.

unstable_uv

ToolchainPluginConfig

uv package manager (experimental). Requires unstable_python.

unstable_uv:
  version: 'latest'

Run moon toolchain info unstable_uv for available settings.

Version Management

Versions can be specified in multiple ways:

Direct Configuration

node:
  version: '20.0.0'
typescript:
  version: '^5.0.0'

Environment Variables

Versions can be set via MOON_<TOOLCHAIN>_VERSION environment variables:

export MOON_NODE_VERSION=20.0.0
export MOON_RUST_VERSION=1.75.0

Proto Integration

Versions are automatically inherited from .prototools:

.prototools

node = "20.0.0"
rust = "1.75.0"

.moon/toolchains.yml

node:
  versionFromPrototools: true
rust:
  versionFromPrototools: true

Complete Example

.moon/toolchains.yml

extends: 'https://example.com/shared-toolchains.yml'

moon:
  manifestUrl: 'https://proxy.corp.net/moon/version'

proto:
  version: '0.51.0'

# JavaScript ecosystem
javascript:
  version: 'latest'

node:
  version: '20.0.0'
  versionFromPrototools: true
  config:
    bundledNpm: true
    # Disable npm and use pnpm instead
    npm: false

pnpm:
  version: '8.15.0'
  versionFromPrototools: true

typescript:
  version: '5.3.0'
  config:
    syncProjectReferences: true
    syncProjectReferencesToPaths: true

# Alternative runtimes
bun:
  version: 'latest'

deno:
  version: '1.40.0'

# Other languages
rust:
  version: '1.75.0'
  versionFromPrototools: true

go:
  version: '1.21.0'

# Python (experimental)
unstable_python:
  version: '3.12.0'
  versionFromPrototools: 'python'

unstable_uv:
  version: 'latest'

# Custom toolchain
custom-tool:
  plugin: 'https://cdn.example.com/custom-plugin.wasm'
  version: '1.0.0'
  config:
    customOption: true

Querying Toolchain Info

For detailed information about a specific toolchain’s configuration options:

# View all available settings
moon toolchain info node
moon toolchain info rust
moon toolchain info typescript

# List all configured toolchains
moon toolchain list

Configuration Schemas

Toolchain Configuration

Configuration File

Schema

Core Settings

Moon Configuration

Proto Configuration

Toolchain Plugins

Built-in Toolchains

JavaScript Ecosystem

Package Managers

Other Languages

Version Management

Direct Configuration

Environment Variables

Proto Integration

Complete Example

Querying Toolchain Info

Build docs developers (and LLMs) love

Configuration Schemas

​Configuration File

​Schema

​Core Settings

​Moon Configuration

​Proto Configuration

​Toolchain Plugins

​Built-in Toolchains

​JavaScript Ecosystem

​Package Managers

​Other Languages

​Version Management

​Direct Configuration

​Environment Variables

​Proto Integration

​Complete Example

​Querying Toolchain Info

​Related

Build docs developers (and LLMs) love

Configuration File

Schema

Core Settings

Moon Configuration

Proto Configuration

Toolchain Plugins

Built-in Toolchains

JavaScript Ecosystem

Package Managers

Other Languages

Version Management

Direct Configuration

Environment Variables

Proto Integration

Complete Example

Querying Toolchain Info

Related