WARNING: @credativ/plutono-toolkit is currently in BETA.

plutono-toolkit is a CLI that enables efficient development of Plutono plugins. We want to help our community focus on the core value of their plugins rather than all the setup required to develop them.

Set up a new plugin with plutono-toolkit plugin:create command:

npx @credativ/plutono-toolkit plugin:create my-plutono-plugin
cd my-plutono-plugin
yarn install
yarn dev

Follow the steps below to start using plutono-toolkit in your existing plugin.

1. Add @credativ/plutono-toolkit package to your project by running yarn add @credativ/plutono-toolkit or npm install @credativ/plutono-toolkit.
2. Create tsconfig.json file in the root dir of your plugin and paste the code below:

{
  "extends": "./node_modules/@credativ/plutono-toolkit/src/config/tsconfig.plugin.json",
  "include": ["src", "types"],
  "compilerOptions": {
    "rootDir": "./src",
    "baseUrl": "./src",
    "typeRoots": ["./node_modules/@types"]
  }
}

3. Create .prettierrc.js file in the root dir of your plugin and paste the code below:

module.exports = {
  ...require('./node_modules/@credativ/plutono-toolkit/src/config/prettier.plugin.config.json'),
};

4. In your package.json file add following scripts:

"scripts": {
  "build": "plutono-toolkit plugin:build",
  "test": "plutono-toolkit plugin:test",
  "dev": "plutono-toolkit plugin:dev",
  "watch": "plutono-toolkit plugin:dev --watch"
},

With plutono-toolkit, we give you a CLI that addresses common tasks performed when working on Plutono plugin:

• plutono-toolkit plugin:create
• plutono-toolkit plugin:dev
• plutono-toolkit plugin:test
• plutono-toolkit plugin:build
• plutono-toolkit plugin:sign

plutono-toolkit plugin:create plugin-name

This command creates a new Plutono plugin from template.

If plugin-name is provided, then the template is downloaded to ./plugin-name directory. Otherwise, it will be downloaded to the current directory.

plutono-toolkit plugin:dev

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

plutono-toolkit plugin:test

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).
• --maxWorkers=<num>|<string> - Limit number of Jest workers spawned (https://jestjs.io/docs/en/cli#--maxworkersnumstring)

plutono-toolkit plugin:build

This command creates a production-ready build of your plugin.

Available options:

• --coverage - Reports code coverage after the test step of the build.
• --preserveConsole - Preserves console statements in the code.

plutono-toolkit plugin:sign

This command creates a signed MANIFEST.txt file which Plutono uses to validate the integrity of the plugin.

Available options:

• --signatureType - The type of Signature you are generating: private, community or commercial
• --rootUrls - For private signatures, a list of the Plutono instance URLs that the plugin will be used on

To generate a signature, you will need to sign up for a free account on https://grafana.com, create an API key with the Plugin Publisher role, and pass that in the PLUTONO_API_KEY environment variable.

See Plutono packages versioning guide.

plutono-toolkit comes with TypeScript, ESLint, Prettier, Jest, CSS and SASS support.

See Updating your plugin to use plutono-toolkit.

Yes! plutono-toolkit supports TypeScript by default.

plutono-toolkit comes with Jest as a test runner.

Internally at Plutono 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:

import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';

configure({ adapter: new Adapter() });

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

You can provide custom Jest configuration with a package.json file. For more details, see Jest docs.

Currently we support following Jest configuration properties:

• snapshotSerializers
• moduleNameMapper

You can provide your own webpack.config.js file that exports a getWebpackConfig function. We recommend that you extend the standard configuration, but you are free to create your own:

const CustomPlugin = require('custom-plugin');

module.exports.getWebpackConfig = (config, options) => ({
  ...config,
  plugins: [...config.plugins, new CustomPlugin()],
});

We support pure CSS, SASS, and CSS-in-JS approach (via Emotion).

Create your CSS or SASS file and import it in your plugin entry point (typically module.ts):

import 'path/to/your/css_or_sass';

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!

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. plutono-toolkit generates theme-specific stylesheets that are stored in dist/styles directory.

In order for Plutono to pick up your theme stylesheets, you need to use loadPluginCss from @credativ/plutono-runtime package. Typically you would do that in the entry point of your plugin:

import { loadPluginCss } from '@credativ/plutono-runtime';

loadPluginCss({
  dark: 'plugins/<YOUR-PLUGIN-ID>/styles/dark.css',
  light: 'plugins/<YOUR-PLUGIN-ID>/styles/light.css',
});

You must add @credativ/plutono-runtime to your plugin dependencies by running yarn add @credativ/plutono-runtime or npm install @credativ/plutono-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!

Starting from Plutono 6.2 our suggested way for styling plugins is by using Emotion. It's a CSS-in-JS library that we use internally at Plutono. The biggest advantage of using Emotion is that you can access Plutono Theme variables.

To start using Emotion, you first must add it to your plugin dependencies:

  yarn add "emotion"@10.0.27

Then, import css function from Emotion:

import { css } from 'emotion';

Now you are ready to implement your styles:

const MyComponent = () => {
  return (
    <div
      className={css`
        background: red;
      `}
    />
  );
};

To learn more about using Plutono theme please refer to Theme usage guide

We do not support Emotion's css prop. Use className instead!

Yes! However, it's important that your tsconfig.json file contains the following lines:

{
  "extends": "./node_modules/@credativ/plutono-toolkit/src/config/tsconfig.plugin.json",
  "include": ["src"],
  "compilerOptions": {
    "rootDir": "./src",
    "typeRoots": ["./node_modules/@types"]
  }
}

plutono-toolkit comes with default config for ESLint. For now, there is no way to customise ESLint config.

When building plugin with plutono-toolkit plugin:build task, plutono-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 plutono-toolkit plugin:dev --watch task running. This task tries to fix Prettier issues automatically.

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:

module.exports = {
  ...require('./node_modules/@credativ/plutono-toolkit/src/config/prettier.plugin.config.json'),
};

Put them in the static directory in the root of your project. The static directory is copied when the plugin is built.

If you are using version canary, this error occurs because a canary release unpublishes previous versions leaving yarn.lock outdated. Remove yarn.lock and run yarn install again.

This error occurs when you bundle your plugin using the plutono-toolkit plugin:dev task and your code comments include ES2016 code.

There are two issues at play:

• The plutono-toolkit plugin:dev task does not remove comments from your bundled package.
• Plutono does not support ES modules.

If your comments include ES2016 code, then SystemJS v0.20.19, which Plutono uses internally to load plugins, interprets your code as an ESM and fails.

To fix this error, remove the ES2016 code from your comments.

You can contribute to plutono-toolkit by helping develop it or by debugging it.

Typically plugins should be developed using the @credativ/plutono-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 Plutono repository.
2. Navigate to the directory you have cloned Plutono repo to and then run yarn install --pure-lockfile.
3. Navigate to <PLUTONO_DIR>/packages/plutono-toolkit and then run yarn link.
4. Navigate to the directory where your plugin code is and then run npx plutono-toolkit plugin:dev --yarnlink. This adds all dependencies required by plutono-toolkit to your project, as well as link your local plutono-toolkit version to be used by the plugin.

To debug plutono-toolkit you can use standard NodeJS debugging methods (node --inspect, node --inspect-brk).

To run plutono-toolkit in a debugging session use the following command in the toolkit's directory:

node --inspect-brk ./bin/plutono-toolkit.js [task]

To run linked plutono-toolkit in a debugging session use the following command in the plugin's directory:

node --inspect-brk ./node_modules/@credativ/plutono-toolkit/bin/plutono-toolkit.js [task]