How to create a custom map using Viz plugin

[lucamuroni2000]

Hello everyone, I need help creating a custom plugin with a map that can be customised. I followed the tutorial in the official documentation using Yeoman to generate the plugin, and then I tested it to make sure everything was working. Initially, I had to solve a series of problems in an attempt to incorporate the plugin into the superset image I am building, mainly due to the fact that I do not have a custom Dockerfile, but I use the Dockerfile already present in the superset repository (specifically branch 6.0.0). but after solving them, I reached the point where I don't understand how to get the Mapbox API key from the backend to then render the chart map.

As you can see from the image, Mapbox rightly requires the API key, but I don't know how to pass it from the code.

I tried looking at the code for the maps already in Superset, such as Heatmap or Scatterplot, but I couldn't figure out where the API key set in the backend came from.

[dosubot[bot]]

Hi @lucamuroni2000! I'm Dosu and I’m helping the superset team.

To make your custom map viz plugin work with Mapbox in Superset, follow the same pattern as the built-in map visualizations:

1. Set the Mapbox API key in the backend: In your superset_config.py, set MAPBOX_API_KEY = 'your-mapbox-token'. Superset will also read this from the MAPBOX_API_KEY environment variable if set. This is how all built-in map charts get the key [source].

2. Pass the key from backend to frontend: In your custom viz plugin’s backend (Python) class, add the API key to the payload returned by your get_data method, e.g.:

   from superset import config
   
   def get_data(self, df):
       return {
           # ... your data ...
           "mapboxApiKey": config["MAPBOX_API_KEY"],
       }

   This is exactly how built-in visualizations like MapboxViz and DeckGLMultiLayer do it [source].

3. Use the key in your frontend plugin: In your React (or JS) chart code, read props.data.mapboxApiKey and pass it to Mapbox GL or your map library. Do not hardcode the key in the frontend.

4. Best practice: Always keep API keys in backend config or environment variables and only pass them to the frontend as needed for rendering. Never hardcode them in frontend code or commit them to source control [source].

If you need to expose the key outside of the viz payload (rare), you can extend the frontend bootstrap data by adding keys to FRONTEND_CONF_KEYS or by customizing COMMON_BOOTSTRAP_OVERRIDES_FUNC in your config, but for viz plugins, the payload approach is standard and secure [source].

Let me know if you want a concrete code example for your plugin!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[dosubot[bot]]

To add backend support for your custom visualization plugin in Superset, you need to modify the core repository—third-party plugins can't extend backend functionality yet (this is planned for the future with SIP-151) [source].

Here's how you can do it:

1. Subclass BaseViz: In superset/viz.py, create a new Python class for your visualization by subclassing BaseViz. Assign it a unique viz_type string.

2. Implement get_data: In your new class, override the get_data method to include any custom payload you need (like the Mapbox API key). For example:

   from superset import config
   from superset.viz import BaseViz
   
   class CustomMapViz(BaseViz):
       viz_type = "custom_map"
   
       def get_data(self, df):
           return {
               "data": df.to_dict(orient="records"),
               "mapboxApiKey": config["MAPBOX_API_KEY"],
           }

3. Register your viz_type: Make sure your new backend class is imported and registered so Superset recognizes it. Typically, this means adding it to the viz registry in superset/viz.py.

4. Connect frontend and backend: In your frontend plugin (created with Yeoman), set the key to match your backend viz_type (e.g., "custom_map"). Register it in superset-frontend/src/visualizations/presets/MainPreset.js.

This way, when your chart is rendered, the backend will supply the Mapbox API key in the payload, and your frontend can use it to initialize the map [source].

Until the new plugin architecture lands, these backend changes require modifying the Superset core repo. The upcoming extensions system will allow backend extensibility from plugins without touching the core [source].

Let me know if you want a more detailed code walkthrough or have questions about deployment!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[lucamuroni2000]

@dosubot I tried what you told me, but I keep getting the same error.

[dosubot[bot]]

The most common cause for this error is that the custom visualization plugin isn't fully registered on both the backend and frontend, or the frontend isn't reading the Mapbox API key from the payload.

Here’s what you should check:

1. Backend registration: Make sure your CustomMapViz class is not only defined but also imported somewhere in superset/viz.py (or a module imported by it). Superset only recognizes viz types that are imported so they appear in the viz_types registry. If your class isn't imported, the backend won't serve the correct payload for your chart type, and the frontend won't get the API key [source].

2. Frontend registration: In superset-frontend/src/visualizations/presets/MainPreset.js, you must import your plugin and add it to the plugins array with the key 'custom_map' (matching your backend viz_type). If this step is missed, the frontend won't recognize your chart type and won't render it or process the payload [source].

3. Payload structure: Your backend get_data should return the Mapbox API key as mapboxApiKey at the top level of the payload, just like built-in map charts do. The frontend should read it from props.data.mapboxApiKey and pass it to Mapbox GL as mapboxApiAccessToken or mapboxApiKey [source].

4. Build and restart: After making these changes, rebuild your frontend (npm run build in your plugin and in superset-frontend), and restart your Superset server to pick up backend changes.

5. Debugging: Open your browser’s dev tools, go to the Network tab, and inspect the chart data response for your custom map chart. Confirm that mapboxApiKey is present in the payload. If it’s missing, the backend registration is likely the issue. If it’s present but the map still fails, check your frontend code to ensure it’s reading and passing the key correctly.

Let me know what you find in the network response or if you want a concrete code snippet for any of these steps!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[lucamuroni2000]

@dosubot



That was the response; it didn't find anything. Could you explain how to register the plugin correctly using code? I would like to understand why what I have already done is not correct. If I try to look at other classes such as MapboxViz, there is nothing other than its definition within the code; it is not imported or called in other Python files.

[dosubot[bot]]

Here's how Superset registers custom visualization plugins on the backend and frontend:

Backend:
Superset discovers visualization types by scanning all subclasses of BaseViz in superset/viz.py at import time. To register your custom viz, you must define your class as a subclass of BaseViz with a unique viz_type string, and—crucially—ensure the class is either defined directly in superset/viz.py or imported into it. If your class is in a separate file, you must add an import statement for it in superset/viz.py so it gets picked up when the viz_types registry is built. There is no explicit registration call; the import is what makes it discoverable. This is why MapboxViz works: it's defined in superset/viz.py and thus auto-discovered by the registry logic at the bottom of that file (source).

Frontend:
You must import your plugin in superset-frontend/src/visualizations/presets/MainPreset.js and add it to the plugins array with a key that matches your backend viz_type string (e.g., 'custom_map'). The frontend looks up plugins by this key, so if it doesn't match, or isn't registered, your chart won't render (source).

Troubleshooting checklist:

• Make sure your custom viz class is imported or defined in superset/viz.py before the viz_types registry is built.
• Confirm the frontend plugin key matches the backend viz_type.
• Rebuild your Docker image and restart Superset after code changes.
• If using Docker volumes, check that your changes are reflected in the running container.
• Double-check that the chart you're querying exists in the database.

If you follow these steps, your custom viz should be registered and discoverable by both backend and frontend. If you still get a 404 or "not found," it's almost always due to a missing import or a key mismatch.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}