Tag: @superset-ui/core

One caveat up front. The exact list of breaking changes depends on the two versions you are moving between. The authoritative source is UPDATING.md 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.

Why plugins break at all

Three kinds of coupling exist between a plugin and the Superset it runs in:

• Package coupling. The plugin imports from @superset-ui/core, @superset-ui/chart-controls and often @superset-ui/plugin-chart-echarts. 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.
• Behavioural coupling. 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.
• Toolchain coupling. The plugin is compiled by Superset’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.

Most upgrade pain comes from the second and third, because they do not show up as type errors.

What changed between 3.x and 4.x that plugin authors notice

Node and build tooling

The 4.x frontend requires Node 18. If your plugin’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 superset-frontend/package.json at the target tag.

TypeScript configuration also tightened across the 3.x line. Code that compiled with implicit any or loose null checks can start failing. Fix the types rather than loosening the config; the Superset build uses its own settings, not yours.

Peer dependency pins

Every plugin declares @superset-ui/core and @superset-ui/chart-controls 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:

• The package manager resolves two copies of @superset-ui/core into the bundle. Registries and theme contexts are singletons, so the plugin’s copy cannot see the charts, colour schemes or theme registered by Superset’s copy. The symptom is an error along the lines of “theme is undefined” or a chart that never appears in the picker.
• 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.

Update the pins to match the target Superset before doing anything else.

Time range and axis controls

The GENERIC_CHART_AXES 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:

controlPanelSections: [
  sections.legacyRegularTime,
  // ...
]

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 x_axis control, a time_grain_sqla control, and no legacy time section. Your buildQuery then reads formData.x_axis and includes it in columns rather than assuming a __timestamp column.

Filter box removal

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 extra_form_data on the query object. If your buildQuery manipulated extras or filters by hand, check that native filter values still reach the query. The buildQueryContext helper handles this correctly; hand-rolled query construction sometimes does not.

Cross-filter behaviours

Cross-filtering matured across 3.x and is on by default in 4.x. A plugin that declares Behavior.InteractiveChart is expected to emit and respond to cross-filters properly. Two things to check:

• Emitting. The plugin should call setDataMask with both extraFormData.filters and filterState.value 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.
• Receiving. When another chart filters this one, the filter arrives through the normal query path. Verify the chart re-queries rather than showing stale data.

If the plugin cannot participate in cross-filtering, remove Behavior.InteractiveChart from its metadata so the dashboard does not offer the option.

Theme tokens and styling

Superset’s theme object gained and reorganised tokens through 3.x. Plugins that reach into theme.colors.* or theme.gridUnit should be checked against the theme type exported by the target @superset-ui/core. Hard-coded colours keep working but look wrong in a customised deployment, which is the moment stakeholders notice.

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.

Content Security Policy

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 TALISMAN_CONFIG 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.

Legacy visualisation migrations

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 legacy-plugin-chart-* packages.

How to find out which of these affect you

Do this before touching any code.

• Read `UPDATING.md` from your current tag to the target tag. Note every entry that mentions the frontend, feature flags, @superset-ui, or chart behaviour.
• Diff the feature flag defaults between the two versions in superset/config.py. Any flag that flipped and touches charts or dashboards is a behavioural change your plugin will see.
• Check the two package versions of @superset-ui/core and @superset-ui/chart-controls in superset-frontend/package.json at both tags, and read the changelogs for those packages.
• Grep your plugin for the things listed above: legacyRegularTime, __timestamp, setDataMask, theme.colors, hard-coded colours, external URLs, and any import from a legacy- package.

You now have a list. Usually it is short.

Migration sequence

Work in this order; each step gives you a stable checkpoint.

• Branch the plugin and name the branch for the target Superset version.
• Bump the peer dependencies and dev dependencies to the target versions. Set Node to the target version.
• Build the plugin alone (npm run build). Fix compile and type errors. This clears the package coupling.
• Link it into a Superset checkout at the target tag and run the dev server. Open the chart in Explore. This surfaces registry and theme problems immediately.
• Work through the behavioural list: time controls, filters, cross-filters, CSP. Test each in a dashboard, not only in Explore, because filters and cross-filters only exist on dashboards.
• Restore or re-record thumbnails if the chart’s appearance changed.
• Run the tests and update fixtures for any changed ChartProps shape.
• Build the production image 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.

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.

Tests that make the next upgrade cheaper

• Golden `ChartProps` fixtures. Save a real chartProps object from the running product for each chart configuration you support and assert transformProps output against it. When the shape changes, the diff tells you exactly what moved.
• Saved-chart smoke test. A script that lists every saved chart with your viz_type and loads each one’s data endpoint. Run it against staging after every upgrade.
• Control panel snapshot. A test that renders the control panel config and snapshots the control names. A rename in sharedControls shows up here instead of in production.

Keeping the fork thin

The lines you maintain inside the Superset repository should be two: the dependency in superset-frontend/package.json and the registration in MainPreset.js. 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.

Frequently Asked Questions

Will my Superset 3.x plugin work on 4.x without any changes?

Sometimes, but do not plan for it. A plugin that only uses stable @superset-ui/core 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.

What is the most common cause of a plugin breaking after a Superset upgrade?

Two copies of @superset-ui/core in the same bundle. Registries and theme contexts are singletons, so when the plugin’s copy differs from Superset’s copy, the plugin cannot see the charts, colour schemes or theme that Superset registered. It usually surfaces as “theme is undefined” or a chart that never appears in the picker. Align the peer dependency pins before investigating anything else.

The filter box was removed in 4.x. Do I have to rewrite my plugin?

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.

How long does a 3.x to 4.x plugin migration usually take?

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.

Build It With Andolasoft

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 Plugin Scoping Call is free and 45 minutes; you leave with a written estimate of the migration effort. The wider service is described on the Superset plugin development page, and if the upgrade itself is the worry, the Architecture Review covers upgrade readiness for the whole deployment.

If a Superset upgrade is already on the calendar and the custom charts are the unknown, book a Plugin Scoping Call. 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.