Skip to main content

Plugins

proto supports a pluggable architecture as a means for consumers to integrate and manage custom tools (languages, CLIs, etc) within proto's toolchain. It's not possible for proto to support everything in core directly, so plugins are a way for the community to extend the toolchain to their needs.

Enabling plugins​

Plugins can be enabled by configuring them in .prototools or ~/.proto/config.toml files, within the [plugins] section, which maps a plugin to a locator string. The map key is the plugin name in kebab-case, which is used as the binary/tool name in proto, and also the name for configuration and cache purposes. The map value is a locator string that defines a scope and source location.

.prototools
[plugins]
<id> = "<scope>:<location>"

The following locator patterns are supported:

source:​

The source: locator scope supports both secure URLs and file system paths (relative from the config file). Files will be used as-is, while URLs will be downloaded to ~/.proto/plugins.

.prototools
[plugins]
file-tool = "source:plugins/example.wasm"
url-tool = "source:https://domain.com/path/to/plugins/example.wasm"

github:​

The github: locator scope can be used to target and download an asset from a specific GitHub release. The location must be an organization + repository slug (owner/repo), and the release must have a .wasm asset available to download.

.prototools
[plugins]
github-tool = "github:moonrepo/example-repo"

By default, the latest release will be used and cached for 7 days. If you'd prefer to target a specific release, append the release tag to the end of the location.

.prototools
[plugins]
github-tool = "github:moonrepo/example-repo@v1.2.3"

This strategy is powered by the GitHub API and is subject to rate limiting. If running in a CI environment, we suggesting setting a GITHUB_TOKEN environment variable to authorize API requests with. If using GitHub Actions, it's as simple as:

# In some job or step...
env:
    GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'

Creating plugins​

To ease the plugin development process, proto supports 2 types of plugins, a TOML based plugin for basic use cases, and a WASM based plugin for advanced use cases.