Skip to main content

Get started

Grafana's plugin tools offer an officially supported way to extend Grafana's core functionality. We have designed these tools to help you to develop your plugins faster with a modern build setup and zero configuration.

The plugin tools consist of two packages:

  • create-plugin: A CLI to scaffold new plugins or migrate plugins created with @grafana/toolkit.
  • sign-plugin: A CLI to sign plugins for distribution.

Quick Start​

To scaffold your plugin, follow these steps:

  1. Run the following command:

    npx @grafana/create-plugin@latest

  2. When prompted, enter answers to the given questions. For example:

    ? What is going to be the name of your plugin?: mongodb
    ? What is the organization name of your plugin?: grafana
    ? What type of plugin would you like?: datasource

    If you enter those values for name, organization, and plugin type, then the directory and plugin ID will be named grafana-mongodb-datasource.

    note

    If you have previously built a plugin with @grafana/toolkit, you can use our plugin tools to simplify migration. For more information, refer to Migrate from toolkit.

Before you begin​

Make sure you are using supported a supported OS, Grafana version, and tooling.

Supported operating systems​

Grafana plugin tools work with the following operating systems:

  • Linux
  • macOS
  • Windows 10+ with WSL (Windows Subsystem for Linux)

Supported Grafana version​

We generally recommend that you build for a version of Grafana later than v9.0. For more information about requirements and dependencies when developing with Grafana, see the Grafana developer's guide.

You'll need to have the following tools set up:

Choose a package manager​

When you first run @grafana/create-plugin, choose your package manager: npm, pnpm, or yarn.

Output​

Run the above command to create a directory called <orgName>-<pluginName>-<pluginType> inside the current directory. This directory contains the initial project structure to kickstart your plugin development.

info

The directory name <orgName>-<pluginName>-<pluginType> is based on the answers you gave to the prompts. Use the name of the generated folder when prompted.

Depending on the answers you gave to the prompts, there should now be a structure like:

<orgName>-<pluginName>-<pluginType>
├── .config/
├── .eslintrc
├── .github
│   └── workflows
├── .gitignore
├── .nvmrc
├── .prettierrc.js
├── CHANGELOG.md
├── LICENSE
├── Magefile.go
├── README.md
├── cypress
│   └── integration
├── docker-compose.yaml
├── go.mod
├── go.sum
├── jest-setup.js
├── jest.config.js
├── node_modules
├── package.json
├── pkg
│   ├── main.go
│   └── plugin
├── src
│   ├── README.md
│   ├── components
│   ├── datasource.ts
│   ├── img
│   ├── module.ts
│   ├── plugin.json
│   └── types.ts
└── tsconfig.json

When you've finished installing the tools, open the plugin folder:

Create-plugin prompts reference​

When running the create-plugin command, the following prompts appear:

What is the name of your plugin?​

Enter the name of your plugin. This helps to identify its purpose.

What is the organization name of your plugin?​

Enter the name of your organization. Grafana plugins require an organization name (normally your Grafana account username) to help uniquely identify your plugin.

How would you describe your plugin?​

Give your plugin a description. This will help users more easily understand what it does when the plugin is distributed.

What type of plugin would you like?​

Select from the following choices:

  • app: Create a custom out-of-the-box monitoring experience.
  • datasource: Add support for new databases or external APIs.
  • panel: Add new visualizations to dashboards.
  • scenesapp: Create scenes applications or scenes plugins (that is, dashboard-like experiences in app plugins).

To learn more about the types of plugins, refer to the plugin management guidelines. To learn more about scenes, refer to the Scenes documentation.

Do you want a backend part of your plugin?​

App and data source plugins can have a backend component written in Go. Backend plugins offer powerful features such as:

  • Enable Grafana Alerting for data sources.
  • Connect to non-HTTP services to which a browser normally can’t connect. For example, SQL database servers.
  • Keep state between users. For example, query caching for data sources.
  • Use custom authentication methods and/or authorization checks that aren’t supported in Grafana.
  • Use a custom data source request proxy. To learn more, refer to Backend developer resources.

Do you want to add Github CI and Release workflows?​

Add Github workflows to your development cycle to help catch issues early or release your plugin to the community.

Do you want to add a Github workflow to automatically check Grafana API compatibility on PRs?​

Add a Github workflow to regularly check that your plugin is compatible with the latest version of Grafana.

Key CLI commands​

After create-plugin has finished, you can run built-in commands in the shell:

npm run dev​

Builds the plugin in development mode and runs in watch mode. Rebuilds the plugin whenever you make changes to the code. You'll see build errors and lint warnings in the console.

npm run test​

Runs the tests and watches for changes.

npm run build​

Creates a production build of the plugin that optimizes for the best performance. Minifies the build and includes hashes in the filenames.

mage -v

Builds backend plugin binaries for Linux, Windows and Darwin.