Why custom Superset plugins need their own upgrade plan
A custom chart plugin needs its own upgrade check because frontend and form data changes break plugins even when the core Superset upgrade succeeds. The platform can start, migrate its metadata database and load every built-in chart while a plugin built against the previous release fails to render, reads a form field that no longer exists or throws errors in the browser. Treat the plugin as a separate deliverable with its own build, its own test cases and its own sign-off, not as a side effect of the platform upgrade.
The changes that matter most for plugins are in the release notes. Superset 5.0 upgraded React from 16.13.1 to 17.0.2, so custom frontend extensions or plugins may need updates. Superset 6.0 moved the chart layer to Ant Design 5 and renamed ECharts series form data fields, for example x_axis_sort_series became x_axis_sort, so any plugin that reads or writes the old names will misbehave. Superset's upgrade documentation also points to Ant Design 6 as a later change, which means a team that skips 6.0 still has ahead of it another frontend dependency shift. Plan one review per release line you cross, not one review for the whole jump, and confirm the exact breaking change list for your target version in the project's UPDATING.md notes before you estimate the work.
Superset is licensed under Apache-2.0 and has no paid edition, so there is no vendor upgrade service to buy. The effort is internal engineering time, a partner engagement or a mix of both, and the cost is driven by how many plugins you maintain, how deeply they depend on Superset internals and how well your existing code is covered by tests. Follow the supported path in the Superset upgrade guide: back up the metadata database, run superset db upgrade and superset init, and test in staging before production. Before you start, confirm which plugins your organization depends on and who owns each one, because an unowned plugin is the one most likely to be left broken after the upgrade.
What changes in each release and what it does to plugins
This table compares the three upgrade-related changes that most often affect custom chart plugins, with the impact on each and the action to take. Read each row as a checklist item for your plugin code, saved charts and build dependencies before you schedule the upgrade. Confirm the Ant Design details against the project's UPDATING.md notes, since the supplied facts do not list specific component or token changes.
| Change | Impact on plugins | Action needed |
|---|---|---|
| Superset 5.0.0 upgrades React from 16.13.1 to 17.0.2 | Custom frontend extensions or plugins that depend on React 16 behavior may fail to build or render | Inventory React usage in each plugin, update peer dependencies, and rebuild the frontend in staging |
| Superset 6.0.0 renames ECharts series form data fields, such as x_axis_sort_series to x_axis_sort | Saved charts that store the old field names may stop applying sort settings, and plugin control code that reads the old names will break | Search plugin code and saved chart definitions for old field names, add mapping logic if needed, and test each chart type |
| Ant Design 5 arrives in 6.0 | Component imports, theme tokens and prop names used by plugins may no longer match what Superset provides | Confirm the Ant Design 5 changes in UPDATING.md, then update imports, tokens and props and check the plugin renders in each theme |
| Ant Design 6 is expected in the next major line | Changes that were valid on Ant Design 5 may need another pass, and plugins that copy Superset components will need matching updates | Check the release notes for the next line once published, and avoid pinning plugin code to deprecated component APIs now |
| Plugin build and bundling against Superset packages | Version mismatches between the plugin and the Superset frontend packages can cause runtime errors that appear only after upgrade | Pin the plugin to a tested Superset version range and rebuild against each target release before deployment |
| Saved charts and dashboards that use the plugin | Existing charts may render with defaults or errors even when the plugin code compiles | Export a sample of charts before upgrade, then compare rendered output and control values after upgrade in staging |
Inventory and back up before touching plugin code
Four preparation steps come before any plugin code changes. Each one protects a different part of the upgrade: what you own, how you roll back, where you test, and how you prove the charts still render the same way.
Plugin inventory
List every custom plugin with its package version, the chart types it registers, its control panel definitions, any custom form data keys it reads or writes, and its frontend dependencies, including React and Ant Design versions. Record which plugins are forked from upstream and which are your own. Without this list, a team can miss a plugin that only fails when a rarely used chart opens, and the 5.0 React 17 change and the 6.0 ECharts field renames are easy to overlook in code you did not write yourself. Keep the inventory in version control next to the plugin source.
Metadata database backup
Take a verified backup of the metadata database before running any migration, because superset db upgrade and superset init change the tables that store charts, dashboards and their saved form data. Test that the backup restores into a scratch database and record the Superset version it came from. Confirm who can restore it and how long a restore takes in your environment. A plugin rollback does not undo schema changes, so this backup is the only clean way back if a migration goes wrong.
Staging that mirrors production
Build a staging Superset from the same plugin versions, configuration and database driver set as production, then load a copy of the production metadata and the datasets its charts query. Charts that render correctly on a fresh install can break on real saved form data, so the copy must include the charts that use your custom plugins. Confirm that staging uses the same Python version, base image and feature flags as production. Keep staging data-access rules identical so that test users see the same rows.
Saved chart snapshot export
Before the upgrade, export a baseline for every chart that uses a custom plugin. Capture the saved form data as JSON, a rendered image of each chart, and the query text and row counts the chart returns. After the upgrade, repeat the export against staging and compare field by field. Renamed form data keys and changed control defaults show up as differences in the JSON, and a chart that renders blank shows up as a missing image. Store the snapshots with the upgrade record so reviewers can check the result later.
How a plugin breaks after a Superset upgrade
A custom chart plugin can fail in three different ways after a Superset upgrade, and each one shows up differently. The first is a build or dependency failure. Superset 5.0.0 moved React from 16.13.1 to 17.0.2, and the Ant Design line has also changed across releases, so a plugin that bundles or imports its own copies of these libraries can fail to compile, or can load two copies of React and crash at render time. The second is a runtime failure: the plugin builds, but a component, hook or props contract it calls has changed shape, so the chart throws an error or renders an empty panel. Both of these are loud. Someone opens the dashboard and sees a broken chart, and the failure is usually traced to a specific import or prop.
The third path is the one to plan for. Superset 6.0.0 renamed ECharts series form data fields, such as x_axis_sort_series to x_axis_sort. Charts saved before the upgrade still store the old key in their form data. Depending on how the plugin reads its controls, the old value may be ignored and a default applied, so the chart loads, looks plausible, and shows data sorted or grouped differently than the saved configuration. Nothing errors and no build breaks, which makes this the most expensive failure to find. Users may act on wrong numbers for weeks before anyone compares a chart with its previous output. A test plan catches it only if it compares saved charts before and after the upgrade, not just whether the page loads. Ask your plugin owner to list every form data key the plugin reads and writes, check each against the UPDATING notes for the target release, and confirm with the project's UPDATING.md notes which renames apply to your starting version.
The upgrade sequence for plugins, with checks and rollback points
This sequence moves a custom chart plugin from its current Superset release to the target release in a controlled order, so each change is tested against a known baseline and can be reversed at a named point. The output is a plugin build that renders every chart type correctly on staging and a production promotion that has a tested way back.
Back up metadata and record versions
Take a backup of the metadata database before any change, and record the current Superset version, the plugin version, the Node and Python versions, and the plugin's package lock file. Also capture a snapshot of each chart that uses the plugin, including its rendered output and its saved form data, so the pre-upgrade state is documented. The step is done when the backup restores cleanly into a scratch database and the snapshot inventory is stored with the upgrade record. Rollback point: the backup and the recorded versions let you return the metadata and the plugin to the current release.
Build the plugin against the target release
In a separate branch, point the plugin's Superset packages and its frontend dependencies at the target release, and install them from a clean lock file. Review the upgrade notes for that release, including the UPDATING notes for any React or Ant Design changes, and list every item that applies to your plugin. The step is done when the branch installs without peer dependency conflicts and the list of required changes is written down. Rollback point: the production branch is untouched, so discarding this branch restores the current state.
Update React, Ant Design and form data references
Apply the code changes from the list: move components to the React version the target release uses, replace Ant Design components or props that changed, and rename any form data keys that the release renamed. For example, the 6.0.0 release renamed ECharts series sort fields such as x_axis_sort_series to x_axis_sort, so the plugin's control panel and transform functions must read the new key, with a fallback for saved charts that still store the old one. The step is done when a search for old key names returns no matches outside the migration code. Rollback point: each change is a separate commit, so you can revert a single component or key change without losing the others.
Run unit tests and the production build
Run the plugin's unit tests, its type checks and its linter, then run the production build that Superset uses to load plugins. Add or update tests for the form data transforms, especially the renamed keys, so that old saved configurations are proven to map to the new fields. The step is done when all checks pass on a clean checkout and the built bundle loads in an isolated Superset development environment without console errors. Rollback point: a failing check stops promotion and keeps the work on the branch, with no change to staging or production.
Deploy to staging and render each chart type
Deploy the target Superset release and the new plugin build to a staging environment restored from the production metadata backup. Open each saved chart that uses the plugin, render it, and test each chart type the plugin supports, including filters, drill actions, tooltips, empty results and large result sets. Confirm the plugin's tests reflect what you see. The step is done when every saved chart renders and the defects found are logged and fixed. Rollback point: staging is a copy, so it can be rebuilt from the backup and the previous plugin build at any time.
Run the database upgrade sequence in staging
On the staging metadata database, run superset db upgrade and then superset init, in that order, as the Superset upgrade documentation describes. Review the migration output for any table locks or long operations, and confirm the Superset service starts and logs in without errors. The step is done when the migrations complete, the initialization completes, and the plugin still loads on the upgraded instance. Rollback point: restore the staging database from the backup taken in the first step and redeploy the previous Superset release, which keeps the test repeatable.
Compare charts with the pre-upgrade snapshot
Compare the staging renders with the snapshots from the first step, chart by chart, looking at layout, labels, colors, sorting, number formats and the data returned for the same query. Record each difference as either an intended change from the release notes or a defect, and fix the defects before you continue. Ask a dashboard owner to sign off on the charts they use. The step is done when every difference is classified and the owners have approved the results in writing. Rollback point: if a defect cannot be fixed before the planned change window, keep production on the current release and the current plugin.
Promote to production with a rollback point
Take a fresh metadata database backup immediately before the production change, then apply the same database upgrade sequence and deploy the tested plugin build to production. Render a sample of production charts and dashboards and watch the logs for errors after the change. The step is done when the production checks match staging and the upgrade record is closed. Rollback point: keep the pre-change backup, the previous Superset image and the previous plugin build available until the owners have confirmed the dashboards, and restore them if a defect appears.
A test plan for each upgrade path
Superset 5.0 upgraded React from 16.13.1 to 17.0.2, so any plugin that depends on React 16 behavior, bundles its own React copy, or uses rendering patterns that changed needs a build and a browser check before it reaches users. Start by reading the React entries in UPDATING.md for 5.0 and comparing them with your plugin's dependency list.
- Plugin rendering: Load each custom chart type on a staging dashboard and confirm it mounts, updates when filters change, and logs no console errors.
- Duplicate React copies: Inspect the built bundle for a second React instance, which causes hook errors. Confirm the plugin's React peer dependency matches the version Superset ships.
- Control panel defaults: Open the chart editor for each plugin and confirm that default values populate as they did before the upgrade.
- Saved chart loading: Open charts saved on the older release and compare them with pre-upgrade screenshots.
- Export and embedding: Test image and CSV export, along with any embedded iframe or SDK path that loads the plugin.
Before the staging run, confirm the plugin builds cleanly against the React version pinned for 5.0.
Superset 6.0 renamed ECharts series form data fields, such as x_axis_sort_series to x_axis_sort, and moved the interface to Ant Design 5. A plugin that reads the old field names may still render but sort or label data incorrectly, and a plugin with custom controls may show layout or styling changes. Confirm the ECharts and Ant Design entries in UPDATING.md for 6.0 before you finalize the test scope.
- Renamed ECharts fields: Search plugin code and saved chart definitions for the old series sort names and map each one to its replacement.
- Ant Design 5 controls: Test every custom control that uses Ant Design components, since component props, tokens and styles may differ.
- Control panel defaults: Confirm that controls reading renamed fields show the values you expect for new and existing charts.
- Saved chart loading: Reopen charts that store the old field names and confirm their sort order and labels still match the originals.
- Theme and export: Compare rendering under the default theme and any custom theme, then test every export path.
Record which form data fields your plugin reads, so you can confirm each one against the 6.0 notes.
The next line is the 7.0 series, which the GitHub releases page lists as a pre-release. Ant Design 6 is planned for that line, and it changes component APIs that custom plugins may import directly. Because the release is not final, test against a release candidate in a non-production environment, and retest after each new candidate. Check the 7.0 entries in UPDATING.md once the final notes are published.
- Ant Design 6 components: Test every custom control, modal, table and form, and compare each component's usage with the Ant Design migration notes.
- Plugin rendering on a candidate: Run each chart type on the candidate build and log any failures by candidate version.
- Control panel defaults: Verify that dropdowns, inputs and toggles keep their values when a chart is edited and saved.
- Saved chart loading and export: Reopen saved charts and test every export and embedded path, including any custom download action.
- Pinned dependencies: Pin the Ant Design version your plugin bundles, and note the exact Superset candidate used in each test report.
Repeat the full test set on the final release, because candidate behavior can change before general availability.
What makes plugin upgrades take longer
This table lists the factors that most often stretch a custom chart plugin upgrade and what to check for each one. Read it before asking for a quote, because the answers to these questions decide whether the work is a light compatibility pass or a rebuild of the plugin.
| Driver | Effect on effort | What to check |
|---|---|---|
| Number of custom chart types | Each chart type has its own rendering, controls and form data, so effort grows with every type added to the plugin set. | Count the chart types registered by your plugins and note which ones are used in production dashboards. |
| Direct use of Ant Design components | Ant Design moved to version 6 in Superset 6.0 for the Ant Design 5 change and again in 7.0, so direct imports of its components and tokens need review at each step. | List every Ant Design import in plugin code and any custom theme or token overrides. |
| Reliance on ECharts series options | Renamed series options, such as the 6.0 change from x_axis_sort_series to x_axis_sort, require changes in both code and saved configuration. | Search plugin code for ECharts series option keys and compare them against the Superset UPDATING notes for each target release. |
| Saved charts that use renamed fields | Saved charts store form data, so a rename can affect many charts that were never opened during the upgrade. | Query the slice table for charts of your custom types and count those whose params include renamed keys. |
| Custom frontend build pipeline | React 17 in 5.0 and later framework changes can break a bundler, plugin packaging or a pinned dependency, and the build must succeed before any logic is tested. | Record the Node version, package manager, bundler and every pinned React or Ant Design version in the plugin build. |
| Test coverage today | Without unit or visual tests, each change must be checked by hand across chart types and filters, which lengthens the test cycle. | Ask whether plugins have automated tests, snapshot tests or a staging checklist, and how long a manual pass takes today. |
| Maintained in-house or by a third party | Third-party plugins depend on the author's release schedule, and a fork that nobody owns may need full porting. | Confirm who will make the changes, whether the source is available, and whether the author supports the target Superset release. |
Questions teams ask before upgrading custom plugins
How much effort does a custom Superset plugin upgrade take?
Effort depends mostly on how far the plugin reaches into Superset internals and how many releases it has to cross. A plugin that only renders data through the public chart API usually needs less work than one that imports UI components, patches frontend behavior or depends on a specific React or Ant Design version. The main drivers are the number of plugins, the number of breaking changes between your current and target release, the amount of custom styling, and how complete your test coverage is. Ask any partner to size the work from an inventory of your plugins, the Superset versions in scope and the release notes that apply to each one, and to state which items are estimates and which are measured.
Can our own developers upgrade custom visualization plugins internally?
Often yes, if the team knows React, the Superset plugin architecture and the chart build tooling. The upgrade needs frontend engineers who can read the UPDATING.md entries for each release, reproduce the plugin build, and fix dependency and API changes such as the React 17 move in 5.0 or the Ant Design 5 and 6 changes. Teams without that experience usually lose time on build tooling and on finding where a breaking change appears in their code. An internal team can also keep the work moving alongside a partner, with the partner handling the test plan, the staging checks or specific components.
What does the upgrade need from engineers and product owners?
Engineers need to own the code changes, build pipeline and regression fixes, and they need access to a staging Superset that matches production. Product owners need to name the charts and dashboards that matter most, confirm the expected output for each, and decide how to treat charts that break or look different after the change. Both groups should agree on acceptance criteria before work starts, because visual changes in themes or fonts are often judged by people, not tests. Security or data owners should review any plugin that calls external services or handles sensitive query results.
Do custom plugins have to be rebuilt for every Superset release?
Not always, but each release needs to be checked against the plugin. Plugins built on stable public APIs may run unchanged, while plugins that depend on changed frontend libraries, form data fields or build settings need updates before they load. Treat every target release as a compatibility test, even if the plugin code does not change, and keep the plugin's build dependencies pinned so a release can be verified in isolation. Where a plugin is rebuilt, record which Superset version it was built and tested against.
How should saved charts that use old field names be handled?
Saved charts store form data under the field names that existed when they were created, so a rename in a later release can leave them with values the plugin no longer reads. For example, Superset 6.0 renamed ECharts series fields such as x_axis_sort_series to x_axis_sort. Plan for this by listing affected chart types, checking the UPDATING.md notes for each release, and testing a sample of saved charts in staging before production. Handling options include a compatibility mapping in the plugin for old field names, a scripted update of chart metadata, or a documented manual step for owners. Confirm with the partner which option fits your chart count and who approves any change to saved content.
What should a written scope or quote for plugin upgrades include?
A written scope should name the plugins in scope, the source and target Superset versions, and the Ant Design and React changes each plugin must absorb. It should list the test plan for each upgrade, including which charts, dashboards and saved chart types are checked, and what counts as passing. Ask for deliverables such as updated plugin code, a build and deployment procedure, a record of tests run, and a rollback plan. The quote should separate one-time work from any ongoing support or retainer for future releases, state assumptions about your environment, and say what you must provide, such as staging access and sample data. Ask for the basis of every effort figure.
How DeployOpen scopes and delivers plugin upgrades
DeployOpen treats each custom Superset visualization plugin as part of a running system, starting from an inventory of what the plugin depends on in your deployment. The work is fixed-scope and agreed in writing before it starts, with a test plan and handover that your own team can repeat for later Superset releases.
How we scope
- We inventory each custom plugin, its build tooling and the Superset version it currently runs against.
- The written scope lists which target release, plugins and chart types are covered by the upgrade.
- We identify plugins that read ECharts form data fields so renamed fields are scoped explicitly.
- Engagements are fixed-scope, and ongoing support for later releases can be added as a retainer.
How we build
- We check plugin dependencies against the React and Ant Design changes listed in the release notes.
- Plugin code is updated in a branch, with form data migrations written for each renamed field.
- Each plugin is rebuilt and loaded into a staging Superset that mirrors your production metadata database.
- Custom Docker image changes that affect plugin builds are handled in the same change set.
How we hand over
- You receive the updated plugin source, build steps and a record of every changed form data field.
- The test plan covers each chart type, dashboard and saved chart that uses a custom plugin.
- Upgrade runbooks document the order of database backup, migration, plugin deployment and rollback.
- Your team gets a checklist to rerun the plugin tests for the next Superset upgrade.
How we support
- Support after handover can be covered by a retainer that tracks new Superset releases and their UPDATING.md notes.
- Retainers can include plugin regression runs before each planned upgrade in your staging environment.
- We confirm the upgrade path with your team before work begins, including any release candidates in use.
- Changes to plugin code stay in your repositories and infrastructure, so your team keeps full ownership.
