Creating Spin Plugins
- What Are Spin Plugins?
- How to Find and Use a Spin Plugin
- Authoring a Spin Plugin
Spin plugins add new functionality or subcommands to Spin without modifying the
Spin codebase. They make Spin easily extensible while keeping it lightweight.
Spin plugins can add new triggers to Spin (such as the example timer
enable new language SDKs (such as
This document will cover what Spin plugins are, how to use a plugin, and how to create a plugin.
What Are Spin Plugins?
A Spin plugin is an executable that is added to Spin’s plugins directory
$XDG_DATA_HOME/spin/plugins) upon a
spin plugins install <plugin-name>. The
plugin is then ready to be used. If the plugin is an extension to the Spin CLI,
it can now be executed directly as a subcommand:
spin <plugin-name>. If the
plugin is a trigger plugin, it will be executed during
spin up when an app
using that trigger is run.
While for now plugins are assumed to be executables, in the future, support for plugging in WebAssembly modules may be desirable.
How to Find and Use a Spin Plugin
Spin maintains a centralized catalogue of available Spin plugins in the Spin
plugins repository. During plugin
installation, if it does not already exist, Spin fetches the remote catalogue
and creates a local snapshot. To ensure that the local snapshot is up to date,
it is best to run
spin plugins update before installing any plugins.
To list available plugins, run
spin plugins list. Now, decide which plugin to
install. For example, the
js2wasm plugin, which is needed in order to build
$ spin plugins install js2wasm
With the plugin installed, you can now call
spin js2wasm to run it. In this
To upgrade installed plugins to newer versions, run
spin plugin update to
fetch the latest plugins to the local catalogue and
spin plugin upgrade to perform the
upgrade on the installed plugins.
Authoring a Spin Plugin
Spin plugins are implemented as a manifest that points to one or more
.tar.gz archives which contain the plugin executables. So, to create a plugin you must:
- Create tar archives of the executables for the platforms you want to support
- Compose a manifest that describes the plugin and lists the URLs for those tar archives
Packaging a Plugin
After creating your plugin executable, package it along with its license as a
tar.gz archive. Note that the
name field in the plugin manifest must match
both the binary and license name. See the
for more details on naming conventions.
Refer to the aptly named
plugin for an
example of how to build a plugin.
Creating a Spin Plugin Manifest
A Spin plugin manifest is a JSON file that conforms to the a specific JSON
A manifest defines a plugin’s name, version, license, homepage (i.e. GitHub
repo), compatible Spin version, and gives a short description of the plugin. It
also lists the URLs of the tar archives of the plugin for various operating
systems and platforms. The URL can point to the local path to the file by using
the file scheme
file://, for example,
To ensure your plugin manifest is valid, follow the steps in the
Installing a Local Plugin
By default, Spin will look in the plugins catalogue for a plugin. However, when
developing and testing a plugin, it is unlikely to be in the the catalogue. For
both installs and upgrades, the
--url flags can be used to point
to specific local or remote plugin manifests. For example, a local manifest
practice.json can be installed and run as follows:
$ spin plugin install --file practice.json $ spin practice
Contributing a Plugin
If you think the community would benefit from your newly created plugin, create a PR to add it to the Spin plugins catalogue!
Did we miss something?
Let us know how we can improve this project, or contribute an edit to this page. We really appreciate your feedback, to help us build better tools.