Skip to main content

Migrate from toolkit

The @grafana/toolkit tool is now deprecated. If you are still using @grafana/toolkit to scaffold and develop plugins, follow this guide to make the jump to our newest plugin tools.

warning

Our plugin tools use ReactJS. We do not support plugins written in Angular.

Benefits of migrating to the create-plugin tool​

  • More flexible: With create-plugin, you have more control over your plugins and its dependencies. The additional control translates into greater ease of customizing the tooling to fit your specific needs.
  • Faster development: With its out-of-the-box development environment, create-plugin can significantly reduce development time compared to using grafana-toolkit.
  • Improved testing capabilities: Easily test plugins with create-plugin GitHub workflows that automate unit and e2e test runs whenever you push changes to GitHub.
  • Technical support: The grafana-toolkit tool is deprecated and no longer supported by Grafana.
  • Better documentation: The documentation for create-plugin is more comprehensive and easier to discover than grafana-toolkit.

Migrate your plugin to create-plugin​

  1. Perform a back up of all your current files. We recommend that you store the plugin code in a Git repository and run the command on a clean branch so that you can easily identify changes made by the migration command.

  2. In the root directory of the existing plugin (where the package.json file is), run the following command.

npx @grafana/create-plugin@latest migrate
  1. Follow the prompts that appear. Refer to the list below for details about each potential prompt.

Prompts​

When running the migrate command, the following prompts appear. Because of their destructive nature, the prompts have a default value of no.

The following files will be overriden. Would you like to continue?​

Select y to replace the following files and folders in the plugin directory, or create them if they don't exist:

myplugin-directory/
├── .config/
├── .eslintrc
├── .nvmrc
├── .prettierrc.js
├── docker-compose.yaml
├── jest-setup.js
├── jest.config.js
└── tsconfig.json

The following files are required. Can we scaffold them for you?​

Select y to make sure a CHANGELOG.md file exists in the plugin directory.

The following files are possibly not needed anymore. Are you ok with us removing them?​

Select y to delete the following files and folders in the plugin directory:

myplugin-directory/
├── Dockerfile
├── docker-compose.yml
├── webpack/
├── .webpack/
└── .prettierrc

Would you like to update the following dependencies in the package.json?​

Select y to update all the npm dependencies listed by the prompt. The command purposely avoids updating @grafana npm dependencies to reduce potential friction during migration.

Would you like to remove the following possibly unnecessary NPM dependencies?​

Select y to delete the following npm dependencies found in package.json:

{
  "devDependencies": {
-   "ts-loader": "*",
-   "babel-loader": "*",
-   "@grafana/toolkit": "*"
  }
}

Would you like to update the scripts in your package.json? All scripts using grafana-toolkit will be replaced.​

This step updates any npm scripts in the package.json file to match the latest configurations. Any scripts that previously used grafana-toolkit are replaced.

Next steps​

When the migration command finishes running, follow these following steps:

  1. Inspect the changes that were introduced, and then install frontend dependencies.

  2. Run each npm script inside package.json to confirm that the plugin can be built, tested, and signed.

If the plugin had customizations to the toolkit configs (for example, webpack), then refer to Extend configurations to learn how to update them.

If the plugin can be built, but there are problems with Jest tests, then see the Jest advanced configuration issue regarding es modules.

For help with other issues, reach out on Slack or the Community forum.