kibana/x-pack/plugins/canvas/PLUGINS.mdx

---
id: canvasPlugins
slug: /playground/kibana/canvas-plugins
title: Develop Canvas plugins
description: Introduction to
date: 2021-02-18
tags: ['kibana', 'canvas', 'plugins']
related: []
---

To develop your own Canvas plugins, you simply create a Kibana plugin, and register your customizations with Canvas.

The following is a step-by-step guide to adding your own custom random number Canvas plugin.

## Generating a Kibana plugin

```bash
# in the kibana directory
# Rename canvas_example to whatever you want your plugin to be named
node scripts/generate_plugin.js canvas_example
```

This will prompt you for some input. Generally, you can answer as follows:

```
❯ node scripts/generate_plugin.js canvas_example
? Would you like to create the plugin in a different folder? No
? Provide a short description An awesome Kibana plugin
? What Kibana version are you targeting? master
? Should an app component be generated? No
? Should a server API be generated? No
? Should translation files be generated? No
? Would you like to use a custom eslint file? No
```

Once this has completed, go to your plugin directory:

```bash
cd plugins/canvas_example
```

Open that folder in your code editor of choice: `code .`

### Creating a Canvas element and function
Open your plugin's `kibana.json` file. Make sure that `ui` has a value of true, and that `'canvas'` is included in `requiredPlugins`.  It should look something like this.

```json
{
  "id": "canvasExample",
  "version": "7.8.0",
  "server": false,
  "ui": true,
  "requiredPlugins": ["canvas"],
  "optionalPlugins": []
}
```

In your plugin folder, create a new folder `public` and an `index.ts` file within it.

This `index.ts` will need export a Kibana Plugin. You can use this as a starting point for your plugin.

```typescript
import { Plugin, CoreSetup, CoreStart } from '../../../src/core/public';
import { CanvasSetup } from '../../../x-pack/plugins/canvas/public';

interface CanvasExampleSetupPlugins {
  canvas: CanvasSetup;
}

interface CanvasExampleStartPlugins {}

class CanvasExamplePlugin
  implements Plugin<void, void, CanvasExampleSetupPlugins, CanvasExampleStartPlugins> {
  setup(core: CoreSetup, plugins: CanvasExampleSetupPlugins) {}

  start(core: CoreStart) {}
}

export const plugin = () => new CanvasExamplePlugin();
```


Now that the Kibana plugin boilerplate is out of the way, you can start adding functionality to Canvas.

Let's start by adding a new function.

In your `index.ts` add a new function definition:

```typescript
const canvasFunctions = [
  () => ({
    name: 'random',
    help: 'Make a random number between 1 and 100',
    args: {},
    fn() {
      return Math.floor(Math.random() * 100) + 1;
    }
  }),
];
```

Then, in the `setup` method of your plugin, you can add this new function definition to Canvas:

```typescript
setup(core: CoreSetup, plugins: CanvasExampleSetupPlugins) {
  plugins.canvas.addFunctions(canvasFunctions);
}
```

Now, let's add a new Element type.  In your `index.ts` add a new element definition:

```typescript
const elements = [
  () => ({
    name: 'randomNumber',
    displayName: 'Random Number',
    help: 'A random number between 1 and 100',
    image: 'https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltb59c89a07c05b937/5c583a6602ac90e80ba0ab8f/icon-white-circle-elastic-stack.svg',
    expression: 'random | metric "Random Number"',
  }),
];
```

And then, in the `setup` method of the plugin, add this new element definition to Canvas, just like you did with the function:

```typescript
setup(core: CoreSetup, plugins: CanvasExampleSetupPlugins) {
  plugins.canvas.addFunctions(canvasFunctions);
  plugins.canvas.addElements(elements);
}
```

Now, your 'Random Number' element will show up in the list of other Canvas elements.

### Trying out your new plugin

In the terminal, in your plugin's directory, run:

```bash
# In plugins/canvas_example
yarn start
```

- Pull up Kibana in your browser: `http://localhost:5601`
- Go to canvas, and click: "Create workpad"
- Click: "Add element"
- Click: "Other"
- Click: "Random Number"

### Adding a server-side function

> Server side functions may be deprecated in a later version of Kibana

Now, let's add a function which runs on the server.

In your plugin's `kibana.json` file, set `server` to true, and add `"expressions"` as a requiredPlugin.

```typescript
{
  "id": "canvasExample",
  "version": "8.0.0",
  "server": false,
  "ui": true,
  "requiredPlugins": ["canvas", "expressions"],
  "optionalPlugins": []
}
```

Now, much like we made the client plugin, we'll make a server plugin.

Start by making the `server` directory and an `index.ts` file with a shell for your server plugin:

```typescript
import { Plugin, CoreSetup, CoreStart } from '../../../src/core/server';
import { ExpressionsServerSetup } from '../../../src/plugins/expressions/server';

interface CanvasExamplePluginsSetup {
  expressions: ExpressionsServerSetup;
}

class CanvasExamplePlugin implements Plugin {
  setup(core: CoreSetup, plugins: CanvasExamplePluginsSetup) {}

  start(core: CoreStart) {}
}

export const plugin = () => new CanvasExamplePlugin();
```

Now, we'll create a simple function definition that we will register on the server:

```typescript
const serverFunctions = [
  () => ({
    name: 'serverTime',
    help: 'Get the server time in milliseconds',
    args: {},
    fn() {
      return Date.now();
    },
  }),
];
```

And then in our setup method, register it with the Expressions plugin:

```typescript
setup(core: CoreSetup, plugins: CanvasExamplePluginsSetup) {
  serverFunctions.forEach((f) => plugins.expressions.registerFunction(f));
}
```

Now, let's try out our new server function.

- Refresh your browser.
- In the same Canvas workpad:
  - Add another Random Number element as before
  - Click that element to select it
  - Click "Expression editor"
  - Modify the expression to look like this: `serverTime | metric "Server Time in ms"`
  - Click "Run"

You should now see one random number and one "Server Time in ms" value.

> More information about building Kibana Plugins can be found in [src/core](https://github.com/elastic/kibana/blob/main/src/core/README.md)

### My Canvas Plugin stopped working

If your Kibana Server is crashing on startup with a message like

> **FATAL** Error: Unmet requirement "canvas" for plugin "your_plugin_name"

or

> **FATAL** Error: Unmet requirement "interpreter" for plugin "your_plugin_name"

then your plugin was likely created to work on a previous version of Kibana. Starting with version 7.8, the plugin system was redesigned and caused breaking changes to these earlier plugins.

The good news is that all of your existing Canvas extension code can be reused, it just needs to be in an updated Kibana plugin.  Follow the [instructions](#generating-a-kibana-plugin) for creating a new Canvas Kibana plugin, and then add in your existing functions and elements.