This is a tutorial to help you build a "Hello World" viz plugin. The intent is to provide a basic scaffolding to build any sort of data visualization, using any viz libary you'd like (e.g. ECharts, AntV, HighCharts, VX, and D3.).
You can build the Hello World plugin by running a Yeoman generator, which takes a few simple options, and provides this plugin scaffolding.
This Hello World plugin we'll be building is generated automatically with
Yeoman. Let's first get that installed by opening up a terminal and installing
yo module and the
superset package generator
v0.14.7) to create the new plugin.
npm install -g yo @superset-ui/generator-superset
npm installto load up all the npm packages.
npm run dev-serverto spin up the Webpack hot-reloading server
http://localhost:9000and log in with
admin. You're off to the races! (Note: we'll be restarting this later)
superset-uirepository to your computer. It can sit in the same parent directory as your
yarn installand wait for all the packages to get installed
cdinto your local
superset-uirepo folder and then into the
mkdir plugin-chart-hello-world. Note: we highly recommend following the
Create superset-ui chart plugin packageon the following screen:
Give it a name (in our case, go with the default, based on the folder name):
Give it a description (again, default is fine!)
Choose which type of React component you want to make (Class, or Function component).
Select whether you'd like your visualization to be timeseries-based or not
Select whether or not you want to include badges at the top of your README file (really only
needed if you intend to contribute your plugin to the
Admire all the files the generator has created for you. Note that EACH of these is chock full of comments about what they're for, and how best to use them.
Now, we want to see this thing actually RUN! To do that, we'll add your package to Superset and
embrace the magic power of
npm link to see it in-situ, without needing to build the plugin, or
open any PRs on Github.
Add your package to the
package.json file in
Note: Do not run
npm install... explanation below.
Add your plugin to the
MainPreset.js file (located in
superset/superset-frontend/src/visualizations/presets/MainPreset.js) in two places,
alongside the other plugins.
Open a terminal window to
superset/superset-frontend. If you did the Install Superset
steps above, you may still have webpack running there, and you can just stop it with
If not, just open a new window and or
cd to that directory path.
npm link to symlink plugin, using a relative path to
superset-ui and your plugin folder,
npm link ../../superset-ui/plugins/plugin-chart-hello-world.
npm run dev-server. You'll know it worked if you see a line stating
[Superset Plugin] Use symlink source for @superset-ui/plugin-chart-hello-world @ ^0.0.0.
NOTE: If/when you do an
npm install that erases the symlink generated by
npm link, so you'll
have to redo those steps.
NOTE: Dynamic import is a work in progress. We hope you won't even need to DO this soon. We'll
be blogging again when that day comes, we assure you. In short, we have a goal to make editing
MainPreset.js unnecessary, so all the code changes are made in ONE repo.
You should now be able to go to the Explore view in your local Superset and add a new chart! You'll see your new plugin when you go to select your viz type.
Now you can load up some data, and you'll see it appear in the plugin!
The plugin also outputs three things to your browser's console:
formData, a.k.a. everything sent into your viz from the controls
props, as output from the
transformPropsfile for your plugin's consumption
Now you're free to run wild with your new plugin! Here are a few places to start digging in:
Take a look through the full file tree of the plugin. The Readme gives details for the job of each file. EACH of these files has been annotated with extensive comments of what the file is for, and the basics of what you can do with it.
The plugin includes a couple of example controls, but you can certainly continue to add as many as
you need to. The comments/documentation within the controls file is a start, but we recommend
looking at existing
superset-ui plugins for more examples of how you can implement controls to
enhance your queries, work with your data, and change your visualization's display.
buildQuery file where your plugin actually fetches data from the Superset backend. This file
builds he query "context" for your plugin. For a simple plugin, this file needn't do much. There are
a couple changes that need to be made for a timeseries plugin, thus the option in the Yeoman
This file also allows you to add various post-processing operations, to have the Superset backend process your data in various ways (pivoting, etc), but that's a whole other topic we'll cover separately in the near future.
Each of these methods lets you add custom CSS styles using Emotion 👩🎤(a CSS-in-JS approach) which has access to Superset's burgeoning set of theme variables, and also automatically scopes the styles to your plugin, so they don't "leak" to other areas of Superset.
In the Hello World plugin, we've included a few example Theme variables (
typographic weights/sizes). We'll be continuing to add more variables to this theme file as we
continue to push Superset (and the viz plugins) toward the standards of the Superset redesign (see
Because come on... that's the fun part, right?
In this tutorial, you built your plugin in the
superset-ui repo. This means you can use the
built-in build scripts that the repo provides. With your terminal of choice, simply
cd into the
root directory of
supeset-ui and run
yarn build. This will kick off a build of ALL the Superset
plugins and packages, including yours.
The Hello World plugin includes some basic Jest tests to act as a starting point to add unit tests
to your plugin. These do a quick sanity check that the plugin actually loads correctly, and then run
through the basics of making sure that your controls are properly respected by modifying the
resulting data and/or props of the plugin. Running
yarn test from the root directory of
superset-ui will run all the tests for plugins/packages, including your Hello World.
To deploy plugins to a production environment, you must have additional code inside Superset that includes the npm packages of your plugins so they can be installed in the frontend.
One option is to build your Dockerfile so it contains your custom visualization packages.