TypeScript Template Data Source For Grafana
This plugin is a template to help you get started with writing a data source plugin for Grafana in TypeScript.
This template plugin includes:
- Karma and mocha for unit testing in TypeScript
- Mocks for testing and TypeScript typings to be able to compile the plugin.
- A basic Grunt script to build the plugin. Builds TypeScript and copies the required files to the dist directory.
Make a subdirectory named after your plugin in the
data/pluginssubdirectory in your Grafana instance. It does not really matter what the directory name is. When the plugin is installed via the grafana cli, it will create a directory named after the plugin id field in the plugin.json file.
Copy the files in this project into your new plugin subdirectory.
karma start --single-runto run the tests once. There is one failing test for the
testDatasourcein the datasource.ts file.
Restart your Grafana server to start using the plugin in Grafana (Grafana only needs to be restarted once).
grunt watch will build the TypeScript files and copy everything to the dist directory automatically when a file changes. This is useful for when working on the code.
karma start will turn on the karma file watcher so that it reruns all the tests automatically when a file changes.
Changes should be made in the
dist directory and ignore the
Preparing To Publish Your Plugin On Grafana.com
- The plugin id field in the plugin.json file should be unique and should follow the plugin naming convention:
- If the plugin supports annotations, then change the annotations field in the plugin.json file to
- Image links in the plugin are relative to the plugin.json file.
- Everywhere a class is named ChangeMyName, change it your plugin name.
- Commit the
- The README.md should not contain HTML, only Markdown.
- If the README.md file contains links to images, they should be the GitHub link to the image. For example:
Grafana SDK Mocks
The Grafana SDK Mocks package contains mocks for the Grafana classes that a plugin needs to build in TypeScript. It also contains some of the commonly used util classes that are used in plugins. This allows you to write unit tests for your plugin.
It is already included in the package.json but if you need to add it again then the command is:
npm install --save-dev grafana/grafana-sdk-mocks
It also contains a TypeScript Typings file - common.d.ts that you can refer to in your classes that use classes or functions from core Grafana. Use the following triple slash directive to use Grafana classes in your code. The directive will point the TypeScript compiler at the mocks package so that it can find the files it needs to build. Place the directive at the top of all your TypeScript files:
///<reference path="../node_modules/grafana-sdk-mocks/app/headers/common.d.ts" />
Unit Testing with Karma and Mocha and ExpectJS
The Karma configuration uses the SystemJS TypeScript plugin to load files from the src directory and transpile them on the fly. It also uses some simple fakes in the Mocks package so that you can unit test properly.
The settings for Karma are in the karma.conf.js file in the root. If you add any external files, then they need to be added to the SystemJS section to be used in tests.
- First version.