Share a plugin
You’ve just built your first plugin, and now you want to share it with the world. In this guide, you’ll learn how to package and share your plugin with others.
When you build a plugin from source, a
dist directory is created that contains the production build, or plugin assets, for your plugin.
When loading your plugin, Grafana only cares about the plugin assets. Specifically, when the Grafana server starts, it attempts to discover and load plugins like this:
- Look for a
plugin.jsonfile in any of the subdirectories in the plugin directory.
- If a
plugin.jsonwas found, try to load the plugin assets from a
distdirectory in the same directory as the
- If there’s no
distdirectory, try to load the plugin assets from the same directory as the
Now that you know what Grafana needs to load your plugin, let’s see how you can share the plugin with other users.
The best way to share your plugin with the world is to publish it on Grafana Plugins. However, if you’re not ready to make your plugin public just yet, you can still share your plugin by hosting the plugin yourself.
Publish your plugin on Grafana.com
The commit you submit needs to either:
- Contain a
distdirectory with the plugin assets
- Contain the plugin assets in the root directory
We strongly recommend that you don’t check in the plugin assets to the main branch. Instead, use the following steps to create a release branch that contains the plugin assets.
Create a release branch.
git checkout -b release-0.1.x
Build the plugin assets.
-fflag adds the directory even if it’s ignored by
git add -f dist
Create the release commit.
git commit -m "Release v0.1.0"
Create a release tag. You can also create the release on GitHub. If you do, then you can skip this step and the next one.
git tag -a v0.1.0 -m "Create release tag v0.1.0"
Push to GitHub.
follow-tagstells Git to push the release tag along with our release branch.
git push --set-upstream origin release-0.1.x --follow-tags
The next step is to submit the URL to your repository, and the release commit, to the Grafana Plugin Repository.
Host the plugin yourself
If you want to share your plugin by hosting it yourself, then we recommend that you package it by adding the plugin assets to a .zip archive. You can then make the archive available by hosting it yourself.
How you package the plugin depends on whether you want to include the source code or not.
Package the plugin with source code
If you want to distribute the source code along with your plugin assets, then you can archive the entire plugin directory.
To create a .zip archive that contains the plugin assets and source code, run the following commands in your terminal:
cd my-plugin/ yarn build zip my-plugin-0.2.0.src.zip . -r -x "node_modules/*" -x ".git/*"
Package the plugin without source code
If you don’t want to distribute the plugin with the source code, then you can archive the
To create a .zip archive that only contains the bare minimum to load the plugin, run the following commands in your terminal:
cd my-plugin/ yarn build cd dist/ zip my-plugin-0.2.0.nosrc.zip . -r
Package and host your plugin using GitHub
If you host your plugin on GitHub, then you can share the plugin using the following URL:
For example, you can download the Worldmap Panel using the following URL:
Install a packaged plugin
After the user has downloaded the archive containing the plugin assets, they can install it by extracting the archive into their plugin directory.
unzip my-plugin-0.2.0.zip -d YOUR_PLUGIN_DIR/my-plugin