---
slug: moon-v1.33
title: moon v1.33 - Alpha support for toolchain WASM plugins
authors: [milesj]
tags: [toolchain, wasm, plugin, moonx, schema]
image: ./img/moon/v1.33.png
---

With this release, we're stoked to provide an initial release for plugin support.

<!--truncate-->

## Alpha release of toolchain WASM plugins

For over a [year now](./2024-roadmap#plugin-based-architecture), 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](/docs/how-it-works/languages#tier-structure-and-responsibilities). 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](/docs/proto/wasm-plugin)), and support for non-tiered features, like
[`moon init`](/docs/commands/init) and [`moon docker`](/docs/commands/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:

- [Getting started with WASM plugins](/docs/guides/wasm-plugins)
- [Example toolchain WASM plugins](https://github.com/moonrepo/plugins/tree/master/toolchains)
- [`moon_pdk` documentation](https://docs.rs/moon_pdk) (functions, macros, etc)
- [`moon_pdk_api` documentation](https://docs.rs/moon_pdk_api) (structs, enums, etc)

### TypeScript toolchain

To verify that our WASM plugin implementation works correctly, we've
[migrated the TypeScript toolchain entirely to a WASM plugin](https://github.com/moonrepo/plugins/tree/master/toolchains/typescript),
and it's no longer hard-coded in our Rust core! If you've configured
[`typescript`](/docs/config/toolchain#typescript) in
[`.moon/toolchain.yml`](/docs/config/toolchain), 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.

```yml title="moon.yml"
# 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](#dynamic-json-schemas), otherwise your editor may error with
"Property typescript is not allowed".

:::

## Experimental `moonx` executable

Based on a [request from the community](https://github.com/moonrepo/moon/issues/1828), 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.

```shell
$ 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.

## Dynamic JSON schemas

With the initial support for toolchain plugins, the available configuration in
[`.moon/toolchain.yml`](/docs/config/toolchain) and [`moon.yml`](/docs/config/project) 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:

```yaml title=".moon/toolchain.yml"
$schema: './cache/schemas/toolchain.json'
```

```yaml title="app/moon.yml"
$schema: '../.moon/cache/schemas/toolchain.json'
```

The VS Code YAML server does not support the
[`$schema` property](https://github.com/redhat-developer/yaml-language-server/pull/970), but there
is a
[work around](https://github.com/redhat-developer/yaml-language-server?tab=readme-ov-file#using-inlined-schema).
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`](/docs/commands/run) but can be
manually generated with [`moon sync config-schemas`](/docs/commands/sync/config-schemas).

:::

## Other changes

View the [official release](https://github.com/moonrepo/moon/releases/tag/v1.33.0) for a full list
of changes.

- Added support for `moon run ~:build`, which will run the `build` task in the closest project
  (traversing upwards).
- Added `$XDG_DATA_HOME` support when detecting the moon store. Will be used if `$MOON_HOME` is not
  set, and will fallback to `$HOME/.moon`.
- Added elapsed/timing information to child processes and WASM calls within logs.
- Improved the handling of CTRL-C, CTRL-BREAK, and other signals on Windows.
- Updated `moon init` with toolchain plugin support.
- Updated `toolchain.default` in `moon.yml` to support a list of IDs.
- Updated file hashing (via `git hash-object`) to continously pipe stdin to avoid hanging processes.
