Overview

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import VersionLabel from '@site/src/components/Docs/VersionLabel';

Supported formats<VersionLabel version="2.0.0" />

In moon, you can define configuration files in a variety of formats. We currently support the following:

• JSON (.json)
• JSON with comments (.jsonc)
• HCL (.hcl)
• Pkl (.pkl)
• TOML (.toml)
• YAML (.yml, .yaml)

:::info

In moon v1, only YAML (.yml) and Pkl (.pkl) configuration files were supported.

:::

Schema validation<VersionLabel version="1.33.0" />

We support schema validation for all configuration files through JSON Schema, even for formats that are not JSON (depends on tool/editor support). To reference the schema for a specific configuration file, configure the $schema property at the top of the file with the appropriate schema found at .moon/cache/schemas.

<Tabs groupId="configs" defaultValue=".moon/workspace"

$schema: './cache/schemas/workspace.json'

$schema: './cache/schemas/extensions.json'

$schema: './cache/schemas/toolchains.json'

$schema: '../cache/schemas/tasks.json'

$schema: '../path/to/.moon/cache/schemas/project.json'

$schema: '../path/to/.moon/cache/schemas/template.json'

:::info

The schemas are automatically created when running a task. If they do not exist yet, you can run moon sync config-schemas to generate them manually.

:::

:::danger

In older versions of moon, the schema files were located at https://moonrepo.dev/schemas. These URLs are now deprecated, as they do not support dynamic settings. Please update your $schema references to point to the local schema files in .moon/cache/schemas.

:::

Setup & usage

Pkl

Pkl utilizes a client-server architecture, which means that the pkl binary must exist in the environment for parsing and evaluating .pkl files. Jump over to the official documentation for instructions on how to install Pkl.

If you are using proto, you can install Pkl with the following commands.

proto plugin add pkl https://raw.githubusercontent.com/milesj/proto-plugins/refs/heads/master/pkl.toml
proto install pkl --pin

To start using Pkl in moon, simply:

• Install Pkl and the VS Code extension.
• Create configs with the .pkl extension.

:::info

We highly suggest reading the Pkl language reference and the standard library.

:::

Caveats and restrictions

Since this is an entirely new configuration format that is quite dynamic compared to YAML, there are some key differences to be aware of!

• Only files are supported. Cannot use or extend from URLs.

• Each .pkl file is evaluated in isolation (loops are processed, variables assigned, etc). This means that task inheritance and file merging cannot extend or infer this native functionality.

• default is a special feature in Pkl and cannot be used as a setting name. This only applies to template.pkl, but can be worked around by using defaultValue instead.

variables {
  ["age"] {
    type = "number"
    prompt = "Age?"
    defaultValue = 0
}

Example functionality

Loops and conditionals:

tasks {
  for (_os in List("linux", "macos", "windows")) {
    ["build-\(_os)"] {
      command = "cargo"
      args = List(
        "--target",
        if (_os == "linux") "x86_64-unknown-linux-gnu"
          else if (_os == "macos") "x86_64-apple-darwin"
          else "i686-pc-windows-msvc",
        "--verbose"
      )
      options {
        os = _os
      }
    }
  }
}

Local variables:

local _sharedInputs = List("src/**/*")

tasks {
  ["test"] {
    // ...
    inputs = List("tests/**/*") + _sharedInputs
  }
  ["lint"] {
    // ...
    inputs = List("**/*.graphql") + _sharedInputs
  }
}