From bd5d12e92298f7eb487403560bd0742e76b8730b Mon Sep 17 00:00:00 2001
From: Ville Brofeldt <ville.v.brofeldt@gmail.com>
Date: Fri, 14 Jan 2022 14:03:36 +0200
Subject: [PATCH] add docs

---
 .../Contributing/creating-viz-plugins.mdx     | 116 ++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 docs/src/pages/docs/Contributing/creating-viz-plugins.mdx

diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx
new file mode 100644
index 000000000000..a85bc99fddfe
--- /dev/null
+++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx
@@ -0,0 +1,116 @@
+---
+name: Creating Visualization Plugins
+menu: Contributing
+route: /docs/contributing/creating-viz
+index: 9
+version: 1
+---
+
+## 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. 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 plugins by hand.
+
+### Prerequisites
+
+In order to create a new visualization plugin, you need the following:
+
+- Run MacOS or Linux (Windows is not officially supported, but may work)
+- Node 16
+- npm 7 or 8
+
+### Creating a simple Hello World 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:
+
+```bash
+npm i -g yo
+cd superset-frontend/packages/superset-generator
+npm link
+```
+
+After this you can proceed to create your viz plugin. Create a new directory wherever
+you have your repos (we'll assume under `~/src/`) with the prefix
+`superset-plugin-chart` and run the Yeoman generator:
+
+```bash
+cd ~/src
+mkdir superset-plugin-chart-hello-world
+cd superset-plugin-chart-hello-world
+yo @superset-ui/superset
+```
+
+After that the generator will ask a few questions (the defaults should be fine):
+
+```
+$ yo @superset-ui/superset
+
+     _-----_     ╭──────────────────────────╮
+    |       |    │      Welcome to the      │
+    |--(o)--|    │    generator-superset    │
+   `---------´   │        generator!        │
+    ( _´U`_ )    ╰──────────────────────────╯
+    /___A___\   /
+     |  ~  |
+   __'.___.'__
+ ´   `  |° ´ Y `
+
+? Package name: superset-plugin-chart-hello-world
+? Description: Hello World
+? What type of chart would you like? Time-series chart
+   create package.json
+identical .gitignore
+   create babel.config.js
+   create jest.config.js
+   create README.md
+   create tsconfig.json
+   create src/index.ts
+   create src/plugin/buildQuery.ts
+   create src/plugin/controlPanel.ts
+   create src/plugin/index.ts
+   create src/plugin/transformProps.ts
+   create src/types.ts
+   create src/SupersetPluginChartHelloWorld.tsx
+   create test/index.test.ts
+   create test/__mocks__/mockExportString.js
+   create test/plugin/buildQuery.test.ts
+   create test/plugin/transformProps.test.ts
+   create types/external.d.ts
+   create src/images/thumbnail.png
+```
+
+To add the package to Superset, go to the `superset-frontend` subdirectory in your
+Superset source folder (assuming both the `superset-plugin-chart-hello-world` plugin
+and `superset` repos are in the same root directory) and run
+
+```bash
+npm i -S ../../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:
+
+```js
+import { SupersetPluginChartHelloWorld } from 'superset-plugin-chart-hello-world';
+```
+
+to import the plugin and later add the following to the array that's passed to the
+`plugins` property:
+
+```js
+new SupersetPluginChartHelloWorld().configure({ key: 'superset-plugin-chart-hello-world' }),
+```
+
+After that the plugin should show up when you run Superset, e.g. the development server:
+
+```bash
+npm run dev-server
+```