Superset Plugin Compatibility: What Breaks Between 3.x and 4.x and How to Migrate a Plugin

 

A custom chart plugin is compiled into the Superset frontend bundle. That is what makes it fast and

first- class, but it is also why a Superset upgrade can break it: the plugin is built against specific

versions of @superset-ui/core, @superset-ui/chart-controls, and related frontend APIs.

The jump from 3.x to 4.x changed enough that some plugins need more than a simple rebuild—they

may require updates to dependencies, APIs, query handling, or TypeScript code.

This guide is the practical checklist we use when migrating a custom plugin from Superset 3.x to 4.x. It covers the key compatibility checks across index.ts, buildQuery.ts, controlPanel.ts, transformProps.ts, and the React visualization component, along with plugin registration in MainPreset.js. The goal is simple: identify what changed, update only what is necessary, rebuild cleanly, and verify the plugin in Explore and dashboards.

One caveat up front: the exact breaking changes depend on the two Superset versions you are moving between. Always check UPDATING.md and the release notes for every version between your current release and the target. This guide highlights the most important compatibility issues to check when crossing the 3.x to 4.x line.

Explore the Details →