<article class="blog-post">A custom chart plugin is compiled into the Superset frontend bundle. That is what makes it fast and first-class, and it is also why an upgrade can break it: the plugin is built against one version of <code>@superset-ui/core</code> and <code>@superset-ui/chart-controls</code>, and after the upgrade it runs against another. Minor releases rarely matter. Major ones, and the 3.x to 4.x jump in particular, changed enough that most plugins need at least a rebuild and some need real changes.This post is the checklist we work through when we carry a plugin across that line. It assumes you have a plugin structured the way the <a href="https://www.andolasoft.com/blog/how-to-build-a-custom-chart-plugin-for-apache-superset" target="_blank" rel="noopener">build guide</a> describes: <code>index.ts</code>, <code>buildQuery.ts</code>, <code>controlPanel.ts</code>, <code>transformProps.ts</code> and a React component, registered in <code>MainPreset.js</code>.</p>
<p>One caveat up front. The exact list of breaking changes depends on the two versions you are moving between. The authoritative source is <code>UPDATING.md</code> in the Superset repository, read for every release between your current tag and your target. What follows is the set that has affected plugins we maintain.</p>
<h2>Why plugins break at all</h2>
<p>Three kinds of coupling exist between a plugin and the Superset it runs in:</p>
<ul>
<li><strong>Package coupling.</strong> The plugin imports from <code>@superset-ui/core</code>, <code>@superset-ui/chart-controls</code> and often <code>@superset-ui/plugin-chart-echarts</code>. These packages live inside the Superset monorepo and are versioned with it. A type that was exported in one version may be renamed or removed in the next.</li>
<li><strong>Behavioural coupling.</strong> The plugin relies on how Superset builds queries, passes form data, applies filters and handles cross-filter events. Feature flags that flip their default between versions change this behaviour without changing any API.</li>
<li><strong>Toolchain coupling.</strong> The plugin is compiled by Superset&#8217;s webpack, TypeScript and Babel configuration, on the Node version the Superset frontend requires. A stricter TypeScript setting or a newer Node can fail a build that has not changed.</li>
</ul>
<p>Most upgrade pain comes from the second and third, because they do not show up as type errors.</p>
<h2>What changed between 3.x and 4.x that plugin authors notice</h2>
<h3>Node and build tooling</h3>
<p>The 4.x frontend requires Node 18. If your plugin&#8217;s CI still runs Node 16, the first symptom is a build failure with no obvious connection to your code. Align the Node version in your plugin repository, your Dockerfile and your CI with <code>superset-frontend/package.json</code> at the target tag.</p>
<p>TypeScript configuration also tightened across the 3.x line. Code that compiled with implicit <code>any</code> or loose null checks can start failing. Fix the types rather than loosening the config; the Superset build uses its own settings, not yours.</p>
<h3>Peer dependency pins</h3>
<p>Every plugin declares <code>@superset-ui/core</code> and <code>@superset-ui/chart-controls</code> as peer dependencies pinned to specific versions. Those versions moved through the 3.x and 4.x releases. A mismatch produces one of two failures:</p>
<ul>
<li>The package manager resolves two copies of <code>@superset-ui/core</code> into the bundle. Registries and theme contexts are singletons, so the plugin&#8217;s copy cannot see the charts, colour schemes or theme registered by Superset&#8217;s copy. The symptom is an error along the lines of &#8220;theme is undefined&#8221; or a chart that never appears in the picker.</li>
<li>A type or helper the plugin imports no longer exists at the new version, which is a compile error and at least easy to find.</li>
</ul>
<p>Update the pins to match the target Superset before doing anything else.</p>
<h3>Time range and axis controls</h3>
<p>The <code>GENERIC_CHART_AXES</code> feature flag, which lets any column be the x-axis and moves the time range into ad-hoc filters, became the default behaviour in the 3.x line and is the only behaviour in 4.x. Plugins built for 2.x or early 3.x often still use the legacy time section:</p>
<div class="code-block">
<div class="code-header">typescript</div>
<pre><code class="language-typescript">controlPanelSections: [
  sections.legacyRegularTime,
  // ...
]</code></pre>
</div>
<p>This still compiles, and for regular (non-time-series) charts it still works. For time-series plugins it produces a control panel that does not match the rest of the product: users expect a time column and a time grain as controls, and the time range as a filter. Move to the generic axis pattern used by the ECharts time-series plugins: an <code>x_axis</code> control, a <code>time_grain_sqla</code> control, and no legacy time section. Your <code>buildQuery</code> then reads <code>formData.x_axis</code> and includes it in <code>columns</code> rather than assuming a <code>__timestamp</code> column.</p>
<h3>Filter box removal</h3>
<p>Superset 4.0 removed the legacy filter box chart. Plugins are rarely affected directly, but dashboards that used filter boxes to drive your chart now drive it through native filters, which arrive in <code>extra_form_data</code> on the query object. If your <code>buildQuery</code> manipulated <code>extras</code> or <code>filters</code> by hand, check that native filter values still reach the query. The <code>buildQueryContext</code> helper handles this correctly; hand-rolled query construction sometimes does not.</p>
<h3>Cross-filter behaviours</h3>
<p>Cross-filtering matured across 3.x and is on by default in 4.x. A plugin that declares <code>Behavior.InteractiveChart</code> is expected to emit and respond to cross-filters properly. Two things to check:</p>
<ul>
<li><strong>Emitting.</strong> The plugin should call <code>setDataMask</code> with both <code>extraFormData.filters</code> and <code>filterState.value</code> when the user selects an element, and clear both on deselect. Plugins that set only one of these leave the dashboard in an inconsistent state.</li>
<li><strong>Receiving.</strong> When another chart filters this one, the filter arrives through the normal query path. Verify the chart re-queries rather than showing stale data.</li>
</ul>
<p>If the plugin cannot participate in cross-filtering, remove <code>Behavior.InteractiveChart</code> from its metadata so the dashboard does not offer the option.</p>
<h3>Theme tokens and styling</h3>
<p>Superset&#8217;s theme object gained and reorganised tokens through 3.x. Plugins that reach into <code>theme.colors.*</code> or <code>theme.gridUnit</code> should be checked against the theme type exported by the target <code>@superset-ui/core</code>. Hard-coded colours keep working but look wrong in a customised deployment, which is the moment stakeholders notice.</p>
<p>Note for readers on the 5.x line: Superset 5 replaced the theme system with Ant Design 5 design tokens and a JSON theme format. That is a larger change than anything in 3.x to 4.x and deserves its own migration pass.</p>
<h3>Content Security Policy</h3>
<p>4.0 turned on Flask-Talisman and its Content Security Policy by default. Plugins that load scripts, fonts or images from external domains, for example a map tile server or a CDN-hosted library, are blocked unless <code>TALISMAN_CONFIG</code> allows those origins. This is a deployment change rather than a plugin change, but the plugin author is usually the one who has to explain the blank map.</p>
<h3>Legacy visualisation migrations</h3>
<p>4.0 completed the migration of several legacy charts to their ECharts replacements and removed the old implementations. This matters to plugin authors in one specific case: if your plugin extended or copied code from a legacy chart, the shared code it borrowed may be gone. Search your plugin for imports from <code>legacy-plugin-chart-*</code> packages.</p>
<style>
.as-inline-cta{display:flex;align-items:stretch;border-radius:14px;overflow:hidden;<br />background:#eaf4f6;border:1px solid #dee7ea;margin:32px 0}<br />.as-inline-cta__icon{flex:0 0 128px;background-color:#1aa9ca;<br />background-image:radial-gradient(rgba(255,255,255,.35) 1.4px,transparent 1.4px);<br />background-size:11px 11px;display:flex;align-items:center;justify-content:center;padding:20px}<br />.as-inline-cta__icon span{width:64px;height:64px;border-radius:50%;background:#fff;<br />display:flex;align-items:center;justify-content:center;box-shadow:0 2px 6px rgba(0,0,0,.12)}<br />.as-inline-cta__icon svg{width:28px;height:28px;stroke:#0f7f9c;fill:none;stroke-width:2;<br />stroke-linecap:round;stroke-linejoin:round}<br />.as-inline-cta__body{padding:22px 28px;display:flex;flex-direction:column;justify-content:center;gap:8px}<br />.as-inline-cta__body h4{font-size:19px;font-weight:700;color:#1e2246;margin:0}<br />.as-inline-cta__body p{font-size:14.5px;line-height:1.6;color:#45506b;margin:0;max-width:52ch}<br />.as-inline-cta__link{display:inline-flex;align-items:center;gap:5px;font-size:14.5px;<br />font-weight:700;color:#0f7f9c;text-decoration:none;width:max-content}<br />.as-inline-cta__link svg{width:16px;height:16px;stroke:currentColor;fill:none;stroke-width:2.4;<br />stroke-linecap:round;stroke-linejoin:round}<br />.as-inline-cta__link:hover{text-decoration:underline}<br />@media (max-width:560px){.as-inline-cta{flex-direction:column}<br />.as-inline-cta__icon{flex:0 0 auto;width:100%;padding:16px 0}}<br /></style>
<div class="as-inline-cta">
<div class="as-inline-cta__icon"></div>
<div class="as-inline-cta__body">
<h4>Got more than one custom plugin to check?</h4>
<p>Auditing every plugin against this list scales badly past two or three. A Plugin Scoping Call gets you a migration estimate across your whole plugin set, not just one at a time.</p>
<p><a class="as-inline-cta__link" href="https://www.andolasoft.com/what-we-do/superset-plugin-scoping" target="_blank" rel="noopener">Book a Plugin Scoping Call</a></p>
</div>
</div>
<h2>How to find out which of these affect you</h2>
<p>Do this before touching any code.</p>
<ul>
<li><strong>Read `UPDATING.md`</strong> from your current tag to the target tag. Note every entry that mentions the frontend, feature flags, <code>@superset-ui</code>, or chart behaviour.</li>
<li><strong>Diff the feature flag defaults</strong> between the two versions in <code>superset/config.py</code>. Any flag that flipped and touches charts or dashboards is a behavioural change your plugin will see.</li>
<li><strong>Check the two package versions</strong> of <code>@superset-ui/core</code> and <code>@superset-ui/chart-controls</code> in <code>superset-frontend/package.json</code> at both tags, and read the changelogs for those packages.</li>
<li><strong>Grep your plugin</strong> for the things listed above: <code>legacyRegularTime</code>, <code>__timestamp</code>, <code>setDataMask</code>, <code>theme.colors</code>, hard-coded colours, external URLs, and any import from a <code>legacy-</code> package.</li>
</ul>
<p>You now have a list. Usually it is short.</p>
<h2>Migration sequence</h2>
<p>Work in this order; each step gives you a stable checkpoint.</p>
<ul>
<li><strong>Branch the plugin</strong> and name the branch for the target Superset version.</li>
<li><strong>Bump the peer dependencies</strong> and dev dependencies to the target versions. Set Node to the target version.</li>
<li><strong>Build the plugin alone</strong> (<code>npm run build</code>). Fix compile and type errors. This clears the package coupling.</li>
<li><strong>Link it into a Superset checkout at the target tag</strong> and run the dev server. Open the chart in Explore. This surfaces registry and theme problems immediately.</li>
<li><strong>Work through the behavioural list</strong>: time controls, filters, cross-filters, CSP. Test each in a dashboard, not only in Explore, because filters and cross-filters only exist on dashboards.</li>
<li><strong>Restore or re-record thumbnails</strong> if the chart&#8217;s appearance changed.</li>
<li><strong>Run the tests</strong> and update fixtures for any changed <code>ChartProps</code> shape.</li>
<li><strong>Build the production image</strong> from the target tag with the plugin included, deploy to staging, and load every saved chart that uses the plugin. A saved chart carries the form data it was created with; charts saved under the old control panel are where migration bugs hide.</li>
</ul>
<p>Budget half a day for a minor version and one to two days for a major one, assuming a single plugin of moderate complexity. Multiply for plugins that render maps or use WebGL.</p>
<h2>Tests that make the next upgrade cheaper</h2>
<ul>
<li><strong>Golden `ChartProps` fixtures.</strong> Save a real <code>chartProps</code> object from the running product for each chart configuration you support and assert <code>transformProps</code> output against it. When the shape changes, the diff tells you exactly what moved.</li>
<li><strong>Saved-chart smoke test.</strong> A script that lists every saved chart with your <code>viz_type</code> and loads each one&#8217;s data endpoint. Run it against staging after every upgrade.</li>
<li><strong>Control panel snapshot.</strong> A test that renders the control panel config and snapshots the control names. A rename in <code>sharedControls</code> shows up here instead of in production.</li>
</ul>
<h2>Keeping the fork thin</h2>
<p>The lines you maintain inside the Superset repository should be two: the dependency in <code>superset-frontend/package.json</code> and the registration in <code>MainPreset.js</code>. Every upgrade is a rebase of those two lines onto the new tag. If your fork has grown beyond that, the upgrade cost is no longer about the plugin, and it is worth moving the extra code into the plugin package or a separate extension before the next major version.</p>
<h2>Frequently Asked Questions</h2>
<h3>Will my Superset 3.x plugin work on 4.x without any changes?</h3>
<p>Sometimes, but do not plan for it. A plugin that only uses stable <code>@superset-ui/core</code> exports and no time-range controls often survives untouched. Anything that uses the legacy time section, the filter box, hard-coded colours or the older cross-filter callbacks will need work. The only reliable answer comes from building the plugin against the target version and reading the errors.</p>
<h3>What is the most common cause of a plugin breaking after a Superset upgrade?</h3>
<p>Two copies of <code>@superset-ui/core</code> in the same bundle. Registries and theme contexts are singletons, so when the plugin&#8217;s copy differs from Superset&#8217;s copy, the plugin cannot see the charts, colour schemes or theme that Superset registered. It usually surfaces as &#8220;theme is undefined&#8221; or a chart that never appears in the picker. Align the peer dependency pins before investigating anything else.</p>
<h3>The filter box was removed in 4.x. Do I have to rewrite my plugin?</h3>
<p>Only if your plugin depended on it. The filter box was a chart type, not a plugin API, so most custom charts are unaffected. What does change is the surrounding dashboard: filters now come from native dashboard filters and cross-filters, so a plugin that read filter state the old way needs updating to the current hooks.</p>
<h3>How long does a 3.x to 4.x plugin migration usually take?</h3>
<p>For a single plugin with current dependency pins and no legacy time controls, a day is realistic, most of it spent on the build tooling and the test pass. Plugins that span more than one major version, borrow from legacy chart code, or have no tests take substantially longer, and the estimate is worth getting before the upgrade is scheduled rather than after.</p>
<h2>Build It With Andolasoft</h2>
<p>If the plugin was written by someone who has left, if it borrows from legacy chart code, or if the upgrade spans more than one major version, the cheapest first step is a scoping conversation rather than a spike. Our <a href="https://www.andolasoft.com/what-we-do/superset-plugin-scoping" target="_blank" rel="noopener">Plugin Scoping Call</a> is free and 45 minutes; you leave with a written estimate of the migration effort. The wider service is described on the <a href="https://www.andolasoft.com/what-we-do/superset-plugin-development" target="_blank" rel="noopener">Superset plugin development</a> page, and if the upgrade itself is the worry, the <a href="https://www.andolasoft.com/what-we-do/superset-architecture-review" target="_blank" rel="noopener">Architecture Review</a> covers upgrade readiness for the whole deployment.</p>
<p>If a Superset upgrade is already on the calendar and the custom charts are the unknown, <a href="https://www.andolasoft.com/what-we-do/superset-plugin-scoping" target="_blank" rel="noopener">book a Plugin Scoping Call</a>. We will review the plugins you have, tell you which of the changes above apply to each, and give you a written migration estimate before you commit to an upgrade date.</p>
</article>


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

Table of Contents

Related Articles

Quick Links

Products

For Career

For Sales