IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md (#19515)

Browse Source 
Minor grammar and format edits
This commit is contained in:
oddlittlebird 2019-10-02 00:50:13 -07:00 committed by Torkel Ödegaard
parent 738a1dd6f0
commit 2eb4f64b62
1 changed files with 56 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
packages/grafana-toolkit/README.md
View File

@ -1,16 +1,12 @@
> **@grafana/toolkit is currently in ALPHA**. Core API is unstable and can be a subject of breaking changes!
> **WARNING: @grafana/toolkit is currently in ALPHA**. The core API is unstable and can be a subject of breaking changes!
# grafana-toolkit
grafana-toolkit is CLI that enables efficient development of Grafana plugins
## Rationale
Historically, creating Grafana plugin was an exercise of reverse engineering and ceremony around testing, developing and eventually building the plugin. We want to help our community to focus on the core value of their plugins rather than all the setup required to develop them.
grafana-toolkit is a CLI that enables efficient development of Grafana plugins. We want to help our community focus on the core value of their plugins rather than all the setup required to develop them.
## Getting started
Setup new plugin with `grafana-toolkit plugin:create` command:
Set up a new plugin with `grafana-toolkit plugin:create` command:
```sh
npx grafana-toolkit plugin:create my-grafana-plugin
@ -19,10 +15,13 @@ yarn install
yarn dev
```
### Updating your plugin to use grafana-toolkit
In order to start using grafana-toolkit in your existing plugin you need to follow the steps below:
1. Add `@grafana/toolkit` package to your project by running `yarn add @grafana/toolkit` or `npm install @grafana/toolkit`
## Update your plugin to use grafana-toolkit
Follow the steps below to start using grafana-toolkit in your existing plugin.
1. Add `@grafana/toolkit` package to your project by running `yarn add @grafana/toolkit` or `npm install @grafana/toolkit`.
2. Create `tsconfig.json` file in the root dir of your plugin and paste the code below:
```json
{
"extends": "./node_modules/@grafana/toolkit/src/config/tsconfig.plugin.json",
@ -53,64 +52,64 @@ module.exports = {
```
## Usage
With grafana-toolkit we put in your hands a CLI that addresses common tasks performed when working on Grafana plugin:
With grafana-toolkit, we give you a CLI that addresses common tasks performed when working on Grafana plugin:
- `grafana-toolkit plugin:create`
- `grafana-toolkit plugin:dev`
- `grafana-toolkit plugin:test`
- `grafana-toolkit plugin:build`
### Creating plugin
### Create your plugin
`grafana-toolkit plugin:create plugin-name`
Creates new Grafana plugin from template.
This command creates a new Grafana plugin from template.
If `plugin-name` is provided, the template will be downloaded to `./plugin-name` directory. Otherwise, it will be downloaded to current directory.
If `plugin-name` is provided, then the template is downloaded to `./plugin-name` directory. Otherwise, it will be downloaded to the current directory.
### Developing plugin
### Develop your plugin
`grafana-toolkit plugin:dev`
Creates development build that's easy to play with and debug using common browser tooling
This command creates a development build that's easy to play with and debug using common browser tooling.
Available options:
- `-w`, `--watch` - run development task in a watch mode
### Testing plugin
### Test your plugin
`grafana-toolkit plugin:test`
Runs Jest against your codebase
This command runs Jest against your codebase.
Available options:
- `--watch` - runs tests in interactive watch mode
- `--coverage` - reports code coverage
- `-u`, `--updateSnapshot` - performs snapshots update
- `--testNamePattern=<regex>` - runs test with names that match provided regex (https://jestjs.io/docs/en/cli#testnamepattern-regex)
- `--testPathPattern=<regex>` - runs test with paths that match provided regex (https://jestjs.io/docs/en/cli#testpathpattern-regex)
- `--watch` - Runs tests in interactive watch mode.
- `--coverage` - Reports code coverage.
- `-u`, `--updateSnapshot` - Performs snapshots update.
- `--testNamePattern=<regex>` - Runs test with names that match provided regex (https://jestjs.io/docs/en/cli#testnamepattern-regex).
- `--testPathPattern=<regex>` - Runs test with paths that match provided regex (https://jestjs.io/docs/en/cli#testpathpattern-regex).
### Building plugin
### Build your plugin
`grafana-toolkit plugin:build`
Creates production ready build of your plugin
This command creates a production-ready build of your plugin.
## FAQ
### Which version should I use?
Please refer to [Grafana packages versioning guide](https://github.com/grafana/grafana/blob/master/packages/README.md#versioning)
### Which version of grafana-toolkit should I use?
See [Grafana packages versioning guide](https://github.com/grafana/grafana/blob/master/packages/README.md#versioning).
### What tools does grafana-toolkit use?
grafana-toolkit comes with Typescript, TSLint, Prettier, Jest, CSS and SASS support.
### How to start using grafana-toolkit in my plugin?
See [Updating your plugin to use grafana-toolkit](#updating-your-plugin-to-use-grafana-toolkit)
See [Updating your plugin to use grafana-toolkit](#updating-your-plugin-to-use-grafana-toolkit).
### Can I use Typescript to develop Grafana plugins?
Yes! grafana-toolkit supports Typescript by default.
### How can I test my plugin?
grafana-toolkit comes with Jest as a test runner.
Internally at Grafana we use Enzyme. If you are developing React plugin and you want to configure Enzyme as a testing utility, you need to configure `enzyme-adapter-react`. To do so create `<YOUR_PLUGIN_DIR>/config/jest-setup.ts` file that will provide necessary setup. Copy the following code into that file to get Enzyme working with React:
Internally at Grafana we use Enzyme. If you are developing React plugin and you want to configure Enzyme as a testing utility, then you need to configure `enzyme-adapter-react`. To do so, create `<YOUR_PLUGIN_DIR>/config/jest-setup.ts` file that will provide necessary setup. Copy the following code into that file to get Enzyme working with React:
```ts
import { configure } from 'enzyme';
@ -119,21 +118,19 @@ import Adapter from 'enzyme-adapter-react-16';
configure({ adapter: new Adapter() });
```
You can also setup Jest with shims of your needs by creating `jest-shim.ts` file in the same directory: `<YOUR_PLUGIN_DIR_>/config/jest-shim.ts`
You can also set up Jest with shims of your needs by creating `jest-shim.ts` file in the same directory: `<YOUR_PLUGIN_DIR_>/config/jest-shim.ts`
### Can I provide custom setup for Jest?
You can provide custom Jest configuration with a `package.json` file. For more details, see [Jest docs](https://jest-bot.github.io/jest/docs/configuration.html).
You can provide Jest config via `package.json` file. For more details please refer to [Jest docs](https://jest-bot.github.io/jest/docs/configuration.html).
Currently we support following Jest config properties:
Currently we support following Jest configuration properties:
- [`snapshotSerializers`](https://jest-bot.github.io/jest/docs/configuration.html#snapshotserializers-array-string)
- [`moduleNameMapper`](https://jestjs.io/docs/en/configuration#modulenamemapper-object-string-string)
### How can I style my plugin?
We support pure CSS, SASS and CSS-in-JS approach (via [Emotion](https://emotion.sh/)).
We support pure CSS, SASS, and CSS-in-JS approach (via [Emotion](https://emotion.sh/)).
#### Single CSS or SASS file
Create your CSS or SASS file and import it in your plugin entry point (typically `module.ts`):
```ts
@ -143,11 +140,10 @@ The styles will be injected via `style` tag during runtime.
> Note that imported static assets will be inlined as base64 URIs. *This can be subject of change in the future!*
#### Theme specific stylesheets
#### Theme-specific stylesheets
If you want to provide different stylesheets for dark/light theme, then create `dark.[css|scss]` and `light.[css|scss]` files in the `src/styles` directory of your plugin. grafana-toolkit generates theme-specific stylesheets that are stored in `dist/styles` directory.
If you want to provide different stylesheets for dark/light theme, create `dark.[css|scss]` and `light.[css|scss]` files in `src/styles` directory of your plugin. grafana-toolkit will generate theme specific stylesheets that will end up in `dist/styles` directory.
In order for Grafana to pickup up you theme stylesheets you need to use `loadPluginCss` from `@grafana/runtime` package. Typically you would do that in the entrypoint of your plugin:
In order for Grafana to pick up your theme stylesheets, you need to use `loadPluginCss` from `@grafana/runtime` package. Typically you would do that in the entry point of your plugin:
```ts
import { loadPluginCss } from '@grafana/runtime';
@ -158,21 +154,20 @@ loadPluginCss({
});
```
You need to add `@grafana/runtime` to your plugin dependencies by running `yarn add @grafana/runtime` or `npm instal @grafana/runtime`
You must add `@grafana/runtime` to your plugin dependencies by running `yarn add @grafana/runtime` or `npm instal @grafana/runtime`.
> Note that in this case static files (png, svg, json, html) are all copied to dist directory when the plugin is bundled. Relative paths to those files does not change!
#### Emotion
Starting from Grafana 6.2 *our suggested way* for styling plugins is by using [Emotion](https://emotion.sh). It's a CSS-in-JS library that we use internally at Grafana. The biggest advantage of using Emotion is that you can access Grafana Theme variables.
Starting from Grafana 6.2 *our suggested way* for styling plugins is by using [Emotion](https://emotion.sh). It's a CSS-in-JS library that we use internally at Grafana. The biggest advantage of using Emotion is that you will get access to Grafana Theme variables.
To use start using Emotion you first need to add it to your plugin dependencies:
To start using Emotion, you first must add it to your plugin dependencies:
```
yarn add "@emotion/core"@10.0.14
```
Then, import `css` function from emotion:
Then, import `css` function from Emotion:
```ts
import { css } from 'emotion'
@ -190,7 +185,6 @@ To learn more about using Grafana theme please refer to [Theme usage guide](http
> We do not support Emotion's `css` prop. Use className instead!
### Can I adjust Typescript configuration to suit my needs?
Yes! However, it's important that your `tsconfig.json` file contains the following lines:
```json
@ -205,14 +199,13 @@ Yes! However, it's important that your `tsconfig.json` file contains the followi
```
### Can I adjust TSLint configuration to suit my needs?
grafana-toolkit comes with [default config for TSLint](https://github.com/grafana/grafana/blob/master/packages/grafana-toolkit/src/config/tslint.plugin.json). As for now there is now way to customise TSLint config.
grafana-toolkit comes with [default config for TSLint](https://github.com/grafana/grafana/blob/master/packages/grafana-toolkit/src/config/tslint.plugin.json). For now, there is now way to customise TSLint config.
### How is Prettier integrated into grafana-toolkit workflow?
### How is Prettier integrated into grafana-toolkit workflow?
When building plugin with [`grafana-toolkit plugin:build`](#building-plugin) task, grafana-toolkit performs Prettier check. If the check detects any Prettier issues, the build will not pass. To avoid such situation we suggest developing plugin with [`grafana-toolkit plugin:dev --watch`](#developing-plugin) task running. This task tries to fix Prettier issues automatically.
### My editor does not respect Prettier config, what should I do?
In order for your editor to pickup our Prettier config you need to create `.prettierrc.js` file in the root directory of your plugin with following content:
In order for your editor to pick up our Prettier config you need to create `.prettierrc.js` file in the root directory of your plugin with following content:
```js
module.exports = {
@ -220,18 +213,21 @@ module.exports = {
};
```
## Contributing to grafana-toolkit
## Contribute to grafana-toolkit
You can contribute to grafana-toolkit in the by helping develop it or by debugging it.
### Development
Typically plugins should be developed using the `@grafana/toolkit` installed from npm. However, when working on the toolkit, you may want to use the local version. To do that follow the steps below:
### Develop grafana-toolkit
Typically plugins should be developed using the `@grafana/toolkit` installed from npm. However, when working on the toolkit, you might want to use the local version. Follow the steps below to develop with a local version:
1. Clone [Grafana repository](https://github.com/grafana/grafana)
2. Navigate to the directory you have cloned Grafana repo to and run `yarn install --pure-lockfile`
3. Navigate to `<GRAFANA_DIR>/packages/grafana-toolkit` and run `yarn link`
2. Navigate to the directory where your plugin code is and run `npx grafana-toolkit plugin:dev --yarnlink`. This will add all dependencies required by grafana-toolkit to your project as well as link your local grafana-toolkit version to be used by the plugin.
1. Clone [Grafana repository](https://github.com/grafana/grafana).
2. Navigate to the directory you have cloned Grafana repo to and then run `yarn install --pure-lockfile`.
3. Navigate to `<GRAFANA_DIR>/packages/grafana-toolkit` and then run `yarn link`.
2. Navigate to the directory where your plugin code is and then run `npx grafana-toolkit plugin:dev --yarnlink`. This adds all dependencies required by grafana-toolkit to your project, as well as link your local grafana-toolkit version to be used by the plugin.
### Debugging
To debug grafana-toolkit you can use standard [NodeJS debugging methods](https://nodejs.org/de/docs/guides/debugging-getting-started/#enable-inspector) (`node --inspect`, `node --inspect-brk`). To run grafana-toolkit in a debugging session use the following command in the toolkit's directory:
### Debug grafana-toolkit
To debug grafana-toolkit you can use standard [NodeJS debugging methods](https://nodejs.org/de/docs/guides/debugging-getting-started/#enable-inspector) (`node --inspect`, `node --inspect-brk`).
To run grafana-toolkit in a debugging session use the following command in the toolkit's directory:
`node --inspect-brk ./bin/grafana-toolkit.js [task]`