6 tips for improving your Grafana plugin before you publish
Are you putting the final touches on your plugin before you submit it to the Grafana plugin page? In this article, I’ll share a few tips for how to add that extra polish to your plugins. This article assumes that you already have some knowledge of building plugins for Grafana. If you’re looking to build your first plugin, start by following our get started guide.
Tip 1: Help the user get started
How long does it take for someone who’s installed your plugin to get from zero to useful? The more options users need to understand and configure to get started, the more likely they are to give up in the process.
Having a well-written README helps users get a deeper understanding of how to configure and use your plugin. But avoid making it mandatory reading if you can. Ideally, people should be able to understand how to use your plugin without having to leave Grafana.
Here are three things that you can do to help users get started:
Provide usable defaults: Default to a configuration that works for the most common use case. Ideally, the plugin works with little to no configuration from the user.
Provide help text: Use descriptions for form fields, and tooltips for inline fields to explain how to use a certain option. Avoid simply repeating the name of the label. Instead, in 1-2 sentences, explain when they would want to use it, or if it has impact on other options. If a topic needs more explanation, provide a link in your plugin that takes users to the README, where they can read more.
Allow incremental learning: Allow users to learn about one aspect of your plugin at a time. Hide advanced options using switches or categories, and let users opt in when they are ready.
Enlist beta-testers: If you can, find 1-2 people who haven’t used your plugin before and have them provide feedback on what they struggled with. This will give you important hints on what you can do to improve the experience while getting started.
If you’re building a panel plugin, consider automatically detecting fields from the query based on field type rather than relying on hard-coded field names. This increases the chance that users will have something useful right away when they switch between visualizations.
Tip 2: Document the data frame schema for panel plugins
The data frame is the data structure that serves as the interface between data sources and panels. Data sources produce data frames, and panels use them for visualization. If you’re developing a panel plugin, consider documenting the schema it expects rather than only how to use it with a specific data source. By doing this, people using other data sources can figure out how to write the query needed.
- How many fields does it expect?
- What field types does it expect?
- Does it expect a naming convention for the field names?
For example, the built-in graph panel expects a data frame that contains two fields: one time field and one number field. Any data source that can generate a data frame that satisfies those requirements can be used with the graph panel. For more information about data frames, refer to the data frames docs.
Document the data frame schema in your README so that more users can enjoy your plugin. Once you’ve documented the schema, feel free to provide example queries for data sources that are commonly used with your panel.
Tip 3: Add linting and auto-completion to your plugin.json
All plugins have a plugin.json file that contains metadata about the plugin and what capabilities it supports. It can sometimes be hard to remember all the properties and their possible values. Luckily the JSON Schema for the plugin.json file is available on GitHub. Many modern editors and IDEs offer built-in support for JSON Schemas, which means that we can use it to add linting and auto-completion right inside your code editor.
For example, in VS Code you can add the following snippet to your settings.json to enable linting for your plugin.json files.
{
"json.schemas": [
{
"fileMatch": ["/plugin.json"],
"url": "https://raw.githubusercontent.com/grafana/grafana/master/docs/sources/developers/plugins/plugin.schema.json"
}
],
}If you define the schema in the plugin.json, VS Code even provides auto-completion for the different properties.
{
"$schema": "https://github.com/grafana/grafana/raw/master/docs/sources/developers/plugins/plugin.schema.json",
"type": "datasource",
"name": "JSON API",
"id": "marcusolsson-json-datasource"
}Tip 4: Add dynamic badges to your README
While they are hardly the most critical part of plugin development, badges convey useful information at a glance to anyone browsing your README on GitHub. Grafana doesn’t have official support for badges, but you can still use Shields.io together with the Grafana.com API to create dynamic badges that update automatically when you publish a new version to the catalog.
For example, the following link generates a badge that displays the latest version in the plugin catalog. Replace <YOUR_PLUGIN_ID> with the plugin ID of a published plugin, such as the grafana-clock-panel.
https://img.shields.io/badge/dynamic/json?logo=grafana&color=F47A20&label=catalog&prefix=v&query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22<YOUR_PLUGIN_ID>%22%29%5D.version&url=https%3A%2F%2Fgrafana.com%2Fapi%2FpluginsTo give your users a sense of how popular the plugin is, add a badge that shows the number of times the plugin has been downloaded: grafana-clock-panel.
https://img.shields.io/badge/dynamic/json?logo=grafana&color=F47A20&label=downloads&query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22<YOUR_PLUGIN_ID>%22%29%5D.downloads&url=https%3A%2F%2Fgrafana.com%2Fapi%2FpluginsPaste the following Markdown in your README.md to add both of the badges above that link to the plugin page when you click them:
[](https://grafana.com/grafana/plugins/<YOUR_PLUGIN_ID>)
[](https://grafana.com/grafana/plugins/<YOUR_PLUGIN_ID>)Tip 5: Automate your releases using GitHub Actions
At some point, you might want to publish your plugin to the plugin catalog. This means that you need to build, test, sign, and package the plugin to prepare it to be published. Incorrectly packaged plugins is one of the most common review comments when a plugin is submitted to be published.
If your plugin is available on GitHub, be sure to add the GitHub workflows for plugin development to your repository.
The CI workflow helps you catch mistakes early by building and testing your plugin on every commit.
When you’re ready to publish your plugin, use the release workflow to sign, package, and lint your plugin before submitting it for review. The workflow drafts a GitHub release, with the signed and packaged plugin as release assets. The release workflow even lints the plugin using the plugin validator.
Tip 6: Validate your plugin before publishing it
The plugin validator tool can be run on your local machine, or in your CI workflow, to generate a report of any issues that prevent your plugin from getting published.
The easiest way to run the tool is using the Docker image as it requires all the necessary dependencies:
docker run --pull=always grafana/plugin-validator-cli [options] [path/to/plugin_archive.zip]For example:
docker run --pull=always grafana/plugin-validator-cli -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zipSee the repository for full usage instructions.
If you’re using the GitHub workflows from the previous tip, you’re already validating your plugin as part of your release!
Now that you’re ready to publish your plugin, head over to your Grafana Cloud account and submit your plugin for review!
Want to find out other ways to improve your plugin? Check out our Developer Portal and Plugin examples.
