Skip to main content

Get started

Welcome to the world of Grafana plugin creation, where you can enhance Grafana's foundational features. In this guide, you'll learn how to get started by scaffolding a plugin, running it in an efficient development environment, and using its basic features.

Quick Start​

Scaffold a new plugin with a single command! Run the following and answer the prompts:

npx @grafana/create-plugin@latest

Why create a Grafana plugin?​

Grafana plugin development allows you to create many different types of user experiences using supported features. For example, you can make:

  • Panel plugins - new ways of visualizing data
  • Data-source plugins - connections to a new database or other source of data
  • App plugins - integrated out-of-the-box experiences
tip

If this is your first time creating a plugin, we recommend that you familiarize yourself with the fundamentals of plugin types, backend plugins, data frames, and other key concepts. For more, refer to the Introduction to Grafana plugin development.

Use plugin tools to develop your plugins faster​

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 additional configuration required.

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.
info

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

Before you begin​

Make sure you are using 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:

Supported package managers​

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

Scaffold a plugin​

Step 1: Install the create-plugin tool​

Run the following command and answer the prompts:

npx @grafana/create-plugin@latest

For help with the prompts, refer to the Prompts reference.

Step 2: Open the generated folder structure​

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

cd <orgName>-<pluginName>-<pluginType>
npm install

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. This directory contains the initial project structure to kickstart your plugin development.

The file structure should look like this:

<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

For more information about these files, refer to Folder structure.

Step 3: Run your plugin in Docker​

With the create-plugin tool, you can use a Docker container to simplify the configuration, loading, and development processes. For more information, refer to Set up development environment.

Key CLI commands include:

  • Install (npm i)
  • Build the frontend in development mode (npm run dev)
  • Build the backend (optional) (mage -v build:linux)
  • Run the Grafana server (npm run server)

Frequently used CLI commands​

Use the CLI for essential tasks of plugin development, substituting npm for pnpm, or yarn based on your choice of package manager.

mage -v​

Builds backend plugin binaries for Linux, Windows and Darwin.

npm run build​

Compiles and bundles the project using Webpack in production mode.

npm run dev​

Runs Webpack in watch mode for development, continually monitoring for changes.

npm run typecheck​

Performs a type-checking process on the frontend code using TypeScript.

npm run server​

Launches the Grafana development server using Docker.

npm run sign​

Signs the Grafana plugin using the latest version of @grafana/sign-plugin.

info

For a complete list of available CLI commands, refer to the CLI reference.

Next steps​