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.
[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
.
[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.
[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.
[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.