|
| 1 | +--- |
| 2 | +id: get-started |
| 3 | +title: Get started |
| 4 | +description: Get started with Grafana plugin development with the create-plugin tool. |
| 5 | +keywords: |
| 6 | + - grafana |
| 7 | + - plugins |
| 8 | + - plugin |
| 9 | + - create-plugin |
| 10 | + - getting started |
| 11 | +slug: / |
| 12 | +--- |
| 13 | + |
| 14 | +import ScaffoldNPM from '@shared/createplugin-scaffold.md'; |
| 15 | +import InstallNPM from '@shared/createplugin-install.md'; |
| 16 | +import BuildFEDevNPM from '@shared/createplugin-build-fe-dev.md'; |
| 17 | +import BuildFEProdNPM from '@shared/createplugin-build-fe-prod.md'; |
| 18 | + |
| 19 | +# Get started |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +<YouTubeEmbed videoId="AARrATeVEQY" title="Getting Started with Grafana Plugin Development" /> |
| 24 | + |
| 25 | +**Watch our introductory video** to see a step-by-step guide on getting started with your first Grafana plugin. This visual tutorial complements the detailed instructions below and provides practical insights to help you along the way. |
| 26 | + |
| 27 | +## Quick start |
| 28 | + |
| 29 | +Scaffold a new plugin with a single command! Run the following and answer the prompts: |
| 30 | + |
| 31 | +<ScaffoldNPM /> |
| 32 | + |
| 33 | +## Why create a Grafana plugin? |
| 34 | + |
| 35 | +Grafana plugin development allows you to create many different types of user experiences. For example, you can make: |
| 36 | + |
| 37 | +- **Panel plugins** - new ways of visualizing data |
| 38 | +- **Data source plugins** - connections to a new database or other source of data |
| 39 | +- **App plugins** - integrated out-of-the-box experiences |
| 40 | + |
| 41 | +:::tip |
| 42 | + |
| 43 | +If this is your first time creating a plugin, we recommend that you familiarize yourself with the fundamentals of plugin types, frontend and backend components, data frames, and other essentials. Learn more about the [key concepts of Grafana plugin development](/key-concepts/). |
| 44 | + |
| 45 | +::: |
| 46 | + |
| 47 | +## Signature classifications of Grafana plugins |
| 48 | + |
| 49 | +Familiarize yourself with the signature classifications of Grafana plugins, such as the distinction between private and public plugins. |
| 50 | + |
| 51 | +Note that if you want to publish a plugin associated with a commercial offering to the official Grafana catalog, a paid subscription is typically required. Learn more about [Grafana's plugins policy](https://grafana.com/legal/plugins/). |
| 52 | + |
| 53 | +## Use plugin tools to develop your plugins faster |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +The plugin tools consist of two packages: |
| 58 | + |
| 59 | +- `create-plugin`: A CLI to scaffold new plugins or migrate plugins created with `@grafana/toolkit`. |
| 60 | +- `sign-plugin`: A CLI to sign plugins for distribution. |
| 61 | + |
| 62 | +:::info |
| 63 | + |
| 64 | +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](/migration-guides/migrate-from-toolkit.mdx). |
| 65 | + |
| 66 | +::: |
| 67 | + |
| 68 | +## Before you begin |
| 69 | + |
| 70 | +Make sure you are using a supported OS, Grafana version, and tooling. |
| 71 | + |
| 72 | +### Supported operating systems |
| 73 | + |
| 74 | +Grafana plugin tools work with the following operating systems: |
| 75 | + |
| 76 | +- Linux |
| 77 | +- macOS |
| 78 | +- Windows 10+ with WSL (Windows Subsystem for Linux) |
| 79 | + |
| 80 | +### Supported Grafana version |
| 81 | + |
| 82 | +We generally recommend that you build for a version of Grafana later than v10.0. For more information about requirements and dependencies when developing with Grafana, see the [Grafana developer's guide](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md). |
| 83 | + |
| 84 | +### Required tooling |
| 85 | + |
| 86 | +You'll need to have the following tools set up: |
| 87 | + |
| 88 | +- Go ([Version](https://github.com/grafana/plugin-tools/blob/main/packages/create-plugin/templates/backend/go.mod#L3)) |
| 89 | +- [Mage](https://magefile.org/) |
| 90 | +- [LTS](https://nodejs.dev/en/about/releases/) version of Node.js |
| 91 | +- [Docker](https://docs.docker.com/get-docker/) |
| 92 | +- Optionally, [Yarn](https://yarnpkg.com/getting-started/install) or [PNPM](https://pnpm.io/installation) |
| 93 | + |
| 94 | +#### Supported package managers |
| 95 | + |
| 96 | +When you first run `@grafana/create-plugin`, choose your package manager: `npm`, `pnpm`, or `yarn`. |
| 97 | + |
| 98 | +:::note |
| 99 | +The Yarn commands on this website are compatible with Yarn Berry (>=2.0.0). If you are using Yarn 1.x.x we suggest you upgrade to [Yarn Berry](https://yarnpkg.com/migration/guide). Alternatively you can use `yarn create @grafana/plugin` to run commands with Yarn 1.x.x. |
| 100 | +::: |
| 101 | + |
| 102 | +## Scaffold a plugin |
| 103 | + |
| 104 | +### Run the `create-plugin` tool |
| 105 | + |
| 106 | +Run the following command and answer the prompts: |
| 107 | + |
| 108 | +<ScaffoldNPM /> |
| 109 | + |
| 110 | +For help with the prompts, refer to the [CLI commands](./reference/cli-commands.mdx). |
| 111 | + |
| 112 | +### Open the generated folder structure |
| 113 | + |
| 114 | +Open the plugin folder to browse the generated plugin: |
| 115 | + |
| 116 | +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. |
| 117 | + |
| 118 | +The file structure should look like this: |
| 119 | + |
| 120 | +``` |
| 121 | +<orgName>-<pluginName>-<pluginType> |
| 122 | +├── .config/ |
| 123 | +├── .eslintrc |
| 124 | +├── .github |
| 125 | +│ └── workflows |
| 126 | +├── .gitignore |
| 127 | +├── .nvmrc |
| 128 | +├── .prettierrc.js |
| 129 | +├── CHANGELOG.md |
| 130 | +├── LICENSE |
| 131 | +├── Magefile.go |
| 132 | +├── README.md |
| 133 | +├── cypress |
| 134 | +│ └── integration |
| 135 | +├── docker-compose.yaml |
| 136 | +├── go.mod |
| 137 | +├── go.sum |
| 138 | +├── jest-setup.js |
| 139 | +├── jest.config.js |
| 140 | +├── node_modules |
| 141 | +├── package.json |
| 142 | +├── pkg |
| 143 | +│ ├── main.go |
| 144 | +│ └── plugin |
| 145 | +├── src |
| 146 | +│ ├── README.md |
| 147 | +│ ├── components |
| 148 | +│ ├── datasource.ts |
| 149 | +│ ├── img |
| 150 | +│ ├── module.ts |
| 151 | +│ ├── plugin.json |
| 152 | +│ └── types.ts |
| 153 | +└── tsconfig.json |
| 154 | +``` |
| 155 | + |
| 156 | +For more information about these files, refer to [Anatomy of a plugin](/key-concepts/anatomy-of-a-plugin/). |
| 157 | + |
| 158 | +## Build and run your plugin in Docker |
| 159 | + |
| 160 | +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](/set-up/). |
| 161 | + |
| 162 | +Refer to the "Next steps" terminal output following the [scaffolding of a new plugin](#scaffold-a-plugin) to install dependencies, build and run your plugin. |
| 163 | + |
| 164 | +Example output: |
| 165 | + |
| 166 | +``` |
| 167 | +## What's next? |
| 168 | +
|
| 169 | +Run the following commands to get started: |
| 170 | +
|
| 171 | + * cd ./orgName-pluginName-app |
| 172 | + * npm install to install frontend dependencies. |
| 173 | + * npm exec playwright install chromium to install e2e test dependencies. |
| 174 | + * npm run dev to build (and watch) the plugin frontend code. |
| 175 | + * mage -v build:backend to build the plugin backend code. Rerun this command every time you edit your backend files. |
| 176 | + * docker compose up to start a grafana development server. |
| 177 | + * Open http://localhost:3000 in your browser to create a dashboard to begin developing your plugin. |
| 178 | +
|
| 179 | +Note: We strongly recommend creating a new Git repository by running git init in ./org-pluginname-app before continuing. |
| 180 | +
|
| 181 | + * Learn more about Grafana Plugin Development at https://grafana.com/developers/plugin-tools |
| 182 | +
|
| 183 | +``` |
| 184 | + |
| 185 | +### Install dependencies |
| 186 | + |
| 187 | +<InstallNPM /> |
| 188 | + |
| 189 | +### Build the frontend |
| 190 | + |
| 191 | +To build the plugin in watch mode for development and continually monitor for changes, run: |
| 192 | + |
| 193 | +<BuildFEDevNPM /> |
| 194 | + |
| 195 | +To build for production, run: |
| 196 | + |
| 197 | +<BuildFEProdNPM /> |
| 198 | + |
| 199 | +### Build the backend |
| 200 | + |
| 201 | +If your plugin includes a [backend](./key-concepts/backend-plugins/index.md) component, you can build using mage: |
| 202 | + |
| 203 | +```shell |
| 204 | +mage -v build:linux |
| 205 | +``` |
| 206 | + |
| 207 | +#### Build targets |
| 208 | + |
| 209 | +| Option | Description | Example | |
| 210 | +| -------------- | -------------------------------------------- | --------------------- | |
| 211 | +| `build:[arch]` | Builds a binary for a specific architecture. | `mage -v build:Linux` | |
| 212 | + |
| 213 | +List all available Mage targets for additional commands: |
| 214 | + |
| 215 | +```bash |
| 216 | +mage -l |
| 217 | +``` |
| 218 | + |
| 219 | +### Run the Grafana server |
| 220 | + |
| 221 | +To launch the Grafana development server using Docker, run: |
| 222 | + |
| 223 | +```shell |
| 224 | +docker compose up --build |
| 225 | +``` |
| 226 | + |
| 227 | +Congratulations! You've just scaffolded your first plugin which you can now access at [http://localhost:3000](http://localhost:3000). |
| 228 | + |
| 229 | +## Next steps |
| 230 | + |
| 231 | +- Start your plugin journey with one of our [plugin development tutorials](/tutorials/). |
| 232 | +- Learn how to [extend](/how-to-guides) its functionality. |
| 233 | +- Review the [plugin examples](https://github.com/grafana/grafana-plugin-examples) to learn about good practices. |
| 234 | +- Learn how to [package](/publish-a-plugin/package-a-plugin), [sign](/publish-a-plugin/sign-a-plugin), and [publish](/publish-a-plugin/publish-or-update-a-plugin.md) your plugin to the Grafana [plugin catalog](https://grafana.com/plugins). |
0 commit comments