Grafana Plugin Examples

This repository provides several example plugins categorized by their type to demonstrate different use cases and architectures:

App Plugins

• app-basic: Demonstrates a basic app plugin using custom routing.
• app-with-backend: Demonstrates an app plugin with custom routing and a backend component.

Panel Plugins

• panel-basic: Demonstrates a panel plugin that utilizes the time series graph from @grafana/ui to read and update the dashboard time range.

Data Source Plugins

• datasource-basic: Demonstrates a basic data source plugin.
• datasource-with-backend: Demonstrates a data source plugin with a backend component.

Note: These examples use NPM to manage frontend dependencies. While you may use Yarn or PNPM, official support is only provided for NPM.

If your project uses the GitHub Actions supplied by @grafana/create-plugin, signing is automated via a release workflow.

Setup

1. In your GitHub repository, go to Settings > Secrets > Actions.
2. Create a New repository secret named GRAFANA_API_KEY.
3. Paste your Grafana Cloud API key into the Secret field.

Triggering a Release

To trigger the signing and release workflow, push a version tag to GitHub:

1. Bump the version: npm version <major|minor|patch>
2. Push to origin: git push origin main --follow-tags

npm version patch
git push origin main --follow-tags

Testing involves unit tests (Jest), end-to-end tests (Playwright), and running the plugin within a Grafana instance via Docker.

Unit Testing (Jest)

• Watch mode: npm run test (requires git init first).
• CI mode: npm run test:ci (runs all tests and exits).

End-to-End Testing (Playwright)

1. Start Grafana server: Run npm run server. You can specify a version using the GRAFANA_VERSION environment variable (defaults to latest).
2. Run E2E tests: Run npm run e2e after the server is running.

# Unit tests
npm run test
npm run test:ci

# E2E tests
GRAFANA_VERSION=11.3.0 npm run server
npm run e2e

If your plugin is written in TypeScript, you can use @grafana/levitate to verify if the Grafana APIs you are consuming are compatible with specific versions of Grafana. This helps prevent breaking changes when upgrading Grafana core.

To generate a compatibility report against the latest release of the specified Grafana packages, use the is-compatible command. You can target specific packages like @grafana/data, @grafana/ui, and @grafana/runtime.

# Check against latest versions
npx @grafana/levitate@latest is-compatible --path src/module.ts --target @grafana/data,@grafana/ui,@grafana/runtime

# Check against specific versions
npx @grafana/levitate@latest is-compatible --path src/module.ts --target @grafana/data@9.0.5,@grafana/ui@9.0.5,@grafana/runtime@9.0.5

To develop the frontend component of a Grafana data source plugin, use the following npm commands:

• Install dependencies: Run npm install to set up the node environment.
• Development mode: Run npm run dev to build the plugin in development mode with watch functionality.
• Production build: Run npm run build to create a production-ready build.
• Linting: Use npm run lint to check code quality or npm run lint:fix to automatically fix linting issues.

Some examples include integration tests using the @grafana/plugin-e2e package. To run these tests, navigate to the specific example plugin directory and execute the following command via npm:

npm run e2e

Panel plugins allow you to add new types of visualizations to dashboards (e.g., maps, pie charts, lists). Use them to visualize data from queries, navigate between dashboards, or control external systems.

To start development, follow these steps in the frontend directory:

1. Install dependencies: npm install
2. Development mode: Use npm run dev to build and run in watch mode.
3. Production build: Use npm run build for a production-ready build.
4. Linting: Run npm run lint to check code quality or npm run lint:fix to automatically fix issues.

To initialize the backend of your Grafana app plugin, update the grafana-plugin-sdk-go dependency and build the binaries for multiple platforms using mage.

1. Update SDK: Ensure you are using the latest minor version of the Go SDK.
2. Build Binaries: Use mage to compile binaries for Linux, Windows, and Darwin.
3. List Commands: Use mage -l to see all available build targets.

# Update SDK
go get -u github.com/grafana/grafana-plugin-sdk-go
go mod tidy

# Build binaries for Linux, Windows, and Darwin
mage -v

# List available Mage targets
mage -l

If your plugin uses the GitHub Actions workflow supplied by @grafana/create-plugin, signing is automated via a release workflow. You must first configure your Grafana Cloud API key as a GitHub Secret.

1. Configure GitHub Secrets

1. Navigate to Settings > Secrets > Actions in your GitHub repository.
2. Click New repository secret.
3. Name the secret GRAFANA_API_KEY.
4. Paste your Grafana Cloud API key into the Secret field.
5. Click Add secret.

2. Trigger the Signing Workflow

To start the automated signing and release process, push a new version tag to your repository:

npm version <major|minor|patch>
git push origin main --follow-tags

npm version patch
git push origin main --follow-tags

You can use Shields.io combined with the Grafana.com API to create dynamic badges that automatically update when you publish new versions to the marketplace.

To do this, use the URL parameter https://grafana.com/api/plugins/your-plugin-id and query the JSON response for specific fields. You can also include the grafana logo in the parameter.

Available JSON query fields:

• $.downloads: Total number of downloads.
• $.version: The current catalog version.
• $.grafanaDependency: The required Grafana version.
• $.versionSignatureType: The version signature type.

https://img.shields.io/badge/dynamic/json?logo=grafana&query=$.version&url=https://grafana.com/api/plugins/grafana-polystat-panel&label=Marketplace&prefix=v&color=F47A20