website/blog/2025-03-13_moon-v1.33.mdx
With this release, we're stoked to provide an initial release for plugin support.
<!--truncate-->For over a year now, we've talked about supporting WASM-based toolchain plugins... but what's taking so long? Migrating from a "hard-coded in core" approach to a dynamic plugin approach was actually quite difficult, especially in Rust. It took us way longer than we expected.
With that said, we're excited to announce alpha support for WASM-based toolchain plugins. In this
release, we have a working solution, but with partial support for the toolchain's
tiered features. At this point
in time, we provide full support for tier 0, major support for tier 1 excluding lockfile/manifest
parsing, minor support for tier 2, no support for tier 3 (but will use
proto's APIs), and support for non-tiered features, like
moon init and moon docker.
If you're curious, the following WASM function APIs are now available:
register_toolchain - Registers the toolchain and provide metadata for detection and other
purposes.initialize_toolchain - Provides prompts to use during moon init to gather settings values.define_toolchain_config - Defines a configuration schema for use within JSON schemas.define_docker_metadata - Defines metadata related to docker commands.hash_task_contents - Injects content into the task hashing process.prune_docker - Custom operations to run during docker prune.scaffold_docker - Custom operations to run during docker scaffold.sync_project - Runs syncing operations per project (during the SyncProject action).sync_workspace - Runs syncing operations at the workspace root (during the SyncWorkspace
action).We know everyone is very excited about these plugins, so feel free to start using them today! However, since we don't have full tiered support, most of the advanced functionality related to running tasks is currently not supported (except for task hashing which is supported).
Additionally, we do not have documentation yet for these new APIs, but we do have the following resources to help you get started:
moon_pdk documentation (functions, macros, etc)moon_pdk_api documentation (structs, enums, etc)To verify that our WASM plugin implementation works correctly, we've
migrated the TypeScript toolchain entirely to a WASM plugin,
and it's no longer hard-coded in our Rust core! If you've configured
typescript in
.moon/toolchain.yml, then you'll automatically use the new plugin under
the hood.
This is our first step in supporting plugins in core. We chose TypeScript as our 1st plugin because it was the simplest of all the toolchains, was primarily used for project syncing, and did not require all tiered APIs.
With that said, most of the code had to be rewritten when porting, but we tried to keep as much parity as possible. Please report an issues or differences you encounter. Additionally, because TypeScript is now a "true" toolchain, it will appear in the toolchains list for projects and tasks. This is required since it runs operations in the context of the plugin.
Because toolchain plugins are configured differently internally, and since TypeScript is now a plugin, the configuration syntax for disabling the TypeScript toolchain at the project-level has changed. While not a breaking change in this release, the old format will be removed in the future.
# Before
toolchain:
typescript:
disable: true
# After
toolchain:
typescript: false # or null
:::warning
If you use the TypeScript toolchain, you'll need to update your configuration files or editor to point to the newer JSON schemas, otherwise your editor may error with "Property typescript is not allowed".
:::
moonx executableBased on a request from the community, we're
introducing a new executable moonx, which is simply a shorthand for moon run .... In the future
we will expand this with more "shorthand" functionality.
$ moonx app:build
Because of our current release process, the moonx executable is not packaged in the release (on
GitHub), and is instead created the first time moon runs. Furthermore, moonx is not a binary
executable, and is instead a shim (a Bash script on Unix, and a PowerShell (.ps1) script on
Windows). In the future, this will become a true binary.
With the initial support for toolchain plugins, the available configuration in
.moon/toolchain.yml and moon.yml is no longer
static, and is instead dynamic based on the enabled/configured toolchains. Because of this, the JSON
schemas provided at moonrepo.dev and in the GitHub release are not accurate for some toolchain
related settings, but accurate for everything else.
This may lead to a poor developer experience where your editor shows errors for unknown settings. To
remedy this, we now generate dynamic schemas at .moon/cache/schemas with accurate settings. If
you're editor supports the $schema property, you can update them like so:
$schema: './cache/schemas/toolchain.json'
$schema: '../.moon/cache/schemas/toolchain.json'
The VS Code YAML server does not support the
$schema property, but there
is a
work around.
However, that syntax is a bit unfortunate, so our official moon VS Code extension supports updating
.vscode/settings. Simply open the command palette and select "moon: Append YAML schemas
configuration to settings".
:::info
These schemas are automatically generated through moon run but can be
manually generated with moon sync config-schemas.
:::
View the official release for a full list of changes.
moon run ~:build, which will run the build task in the closest project
(traversing upwards).$XDG_DATA_HOME support when detecting the moon store. Will be used if $MOON_HOME is not
set, and will fallback to $HOME/.moon.moon init with toolchain plugin support.toolchain.default in moon.yml to support a list of IDs.git hash-object) to continously pipe stdin to avoid hanging processes.