Creating Visualization Plugins

Visualizations in Superset are implemented in JavaScript or TypeScript. Superset comes preinstalled with several visualizations types (hereafter “viz plugins”) that can be found under the superset-frontend/plugins directory. Viz plugins are added to the application in the superset-frontend/src/visualizations/presets/MainPreset.js. The Superset project is always happy to review proposals for new high quality viz plugins. However, for highly custom viz types it is recommended to maintain a fork of Superset, and add the custom built viz plugins by hand.

Prerequisites

In order to create a new viz plugin, you need the following:

  • Run MacOS or Linux (Windows is not officially supported, but may work)
  • Node.js 16
  • npm 7 or 8

A general familiarity with React and the npm/Node system is also recommended.

Creating a simple Hello World viz plugin

To get started, you need the Superset Yeoman Generator. It is recommended to use the version of the template that ships with the version of Superset you are using. This can be installed by doing the following:

  1. npm i -g yo
  2. cd superset-frontend/packages/generator-superset
  3. npm i
  4. npm link

After this you can proceed to create your viz plugin. Create a new directory for your viz plugin with the prefix superset-plugin-chart and run the Yeoman generator:

  1. mkdir /tmp/superset-plugin-chart-hello-world
  2. cd /tmp/superset-plugin-chart-hello-world

Initialize the viz plugin:

  1. yo @superset-ui/superset

After that the generator will ask a few questions (the defaults should be fine):

  1. $ yo @superset-ui/superset
  2.      _-----_     ╭──────────────────────────╮
  3.     |       |    │      Welcome to the      │
  4.     |--(o)--|    │    generator-superset    │
  5.    `---------´   │        generator!        │
  6.     ( _´U`_ )    ╰──────────────────────────╯
  7.     /___A___\   /
  8.      |  ~  |
  9.    __'.___.'__
  10.  ´   `  |° ´ Y `
  11. ? Package name: superset-plugin-chart-hello-world
  12. ? Description: Hello World
  13. ? What type of chart would you like? Time-series chart
  14.    create package.json
  15.    create .gitignore
  16.    create babel.config.js
  17.    create jest.config.js
  18.    create README.md
  19.    create tsconfig.json
  20.    create src/index.ts
  21.    create src/plugin/buildQuery.ts
  22.    create src/plugin/controlPanel.ts
  23.    create src/plugin/index.ts
  24.    create src/plugin/transformProps.ts
  25.    create src/types.ts
  26.    create src/SupersetPluginChartHelloWorld.tsx
  27.    create test/index.test.ts
  28.    create test/__mocks__/mockExportString.js
  29.    create test/plugin/buildQuery.test.ts
  30.    create test/plugin/transformProps.test.ts
  31.    create types/external.d.ts
  32.    create src/images/thumbnail.png

To build the viz plugin, run the following commands:

  1. npm i --force
  2. npm run build

Alternatively, to run the viz plugin in development mode (=rebuilding whenever changes are made), start the dev server with the following command:

  1. npm run dev

To add the package to Superset, go to the superset-frontend subdirectory in your Superset source folder run

  1. npm i -S /tmp/superset-plugin-chart-hello-world

If you publish your package to npm, you can naturally install directly from there, too. After this edit the superset-frontend/src/visualizations/presets/MainPreset.js and make the following changes:

  1. import { SupersetPluginChartHelloWorld } from 'superset-plugin-chart-hello-world';

to import the viz plugin and later add the following to the array that’s passed to the plugins property:

  1. new SupersetPluginChartHelloWorld().configure({ key: 'ext-hello-world' }),

After that the viz plugin should show up when you run Superset, e.g. the development server:

  1. npm run dev-server