---
title: .moon/extensions
toc_max_heading_level: 6
---

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

<VersionLabel version="2.0.0" header />

The `.moon/extensions.*` file configures extensions that can hook into pipeline events, or be
executed directly. This file is _optional_.

## `extends`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#extends" />

Defines one or many external `.moon/extensions.*`'s to extend and inherit settings from. Perfect for
reusability and sharing configuration across repositories and projects. When defined, this setting
must be an HTTPS URL _or_ relative file system path that points to a valid YAML document!

```yaml title=".moon/extensions.yml" {1}
extends: 'https://raw.githubusercontent.com/organization/repository/master/.moon/extensions.yml'
```

:::caution

Settings will be merged recursively for blocks, with values defined in the local configuration
taking precedence over those defined in the extended configuration.

:::

## How it works

A mapping of extensions that can be downloaded and executed with the [`moon ext`](../commands/ext)
command. An extension is a WASM plugin, and the location of the WASM file must be defined with the
`plugin` field, which requires a
[plugin locator string](../guides/wasm-plugins#configuring-plugin-locations).

```yaml title=".moon/extensions.yml" {2-5}
example:
  plugin: 'file://./path/to/example.wasm'
  # or
  plugin: 'https://example.com/path/to/example.wasm'
```

Additionally, extensions support custom configuration that is passed to the WASM runtime when the
plugin is instantiated. This configuration is defined by inserting additional fields under the
extension name, relative to the `plugin` field. Each extension may have its own settings, so refer
to their documentation for more information.

```yaml title=".moon/extensions.yml" {2-5}
example:
  plugin: 'file://./path/to/example.wasm'
  setting1: true
  setting2: 'abc'
```

## Supported extensions

View the [official guide](../guides/extensions) for all built-in extensions.
