Keeping custom Backstage plugins compatible across upgrades

The count of internal plugins is the most direct driver, because every plugin needs its own dependency bump, build, type check and test run. Each plugin also has its own frontend or backend wiring that may change between releases. A portal with a handful of plugins that share one code style is usually a small job, while a portal with dozens of plugins across several repositories multiplies the review and testing work. Ask any partner to list every plugin, its package type (frontend, backend, common or module) and its owner before estimating. Plugin count is a one-time driver for the first upgrade and a recurring one for every monthly release that touches them.

Yes. Deprecated packages such as @backstage/backend-common and older helper APIs force code changes that cannot be done by a version bump alone, and each removed API adds a rewrite of the call sites that use it. The effort depends on how deep those calls go into your code, so search your plugins for imports of deprecated packages and count the call sites before the work starts. Plugins that already moved to the newer packages carry much less risk. The Backstage Upgrade Helper shows template changes, but it does not rewrite your custom code for you.

Custom extension points and plugin-to-plugin contracts raise effort because they depend on internal interfaces that Backstage does not test on your behalf. When the core framework changes how a registration or extension is wired, every internal plugin that exposes or consumes your extension points must change in step. Plugins that depend only on the public, documented APIs are cheaper to move. Document each extension point, its consumers and its owner, so the upgrade team knows which changes can cascade across the portal.

Without automated tests, the only way to confirm a plugin still works after an upgrade is manual checking, which grows with every page, route and catalog view the plugin touches. Teams often find breakage late in staging or in front of users. Unit tests for backend routes, catalog processors and frontend components, plus a smoke test of the running app, let the upgrade team find failures on the first build. Ask whether each plugin has tests that run in CI and how long a full run takes. Plugins with no tests should be counted as higher effort in any quote.

Community plugins add effort because their maintainers release on their own schedule, and some have moved to the Backstage community-plugins repository with new package names. Your custom plugins may depend on a community package that has not yet supported the Backstage release you are targeting, which blocks the whole upgrade until a version is found or the dependency is replaced. Check each community dependency's release history, maintenance status and supported Backstage version before you plan. Keep a list of pinned versions so the team can see which upgrade is blocked by which package.

Yes. The more releases an app has skipped, the more deprecations, template changes and API moves it has to absorb in one pass. Staying on the monthly main line keeps each step small, and an app that has skipped many months may need several steps with testing between them. Count how many releases your app is behind using the Backstage releases page and the Upgrade Helper before you estimate. The gap is a one-time cost for the catch-up, but a steady monthly cadence keeps it recurring and small.

Each owning team sets its own release timing, test coverage and review capacity, so the number of owners determines how much coordination the upgrade needs. When several teams own plugins that depend on each other, one team's delay holds up everyone else. A single platform team that owns all plugins can move faster but may become a bottleneck. Confirm who signs off each plugin, who merges fixes, and who answers for a failed upgrade before the work starts. Clear ownership is often the cheapest way to reduce upgrade time.

The cost follows the number of plugins, how far they reach into core APIs, and how often your Backstage version moves. A plugin that only uses stable frontend components and the public plugin API is cheap to carry forward. A plugin that imports internal packages, depends on deprecated modules such as @backstage/backend-common, or extends backend behavior through older extension points needs more work on every bump. Other cost drivers are the size of your test coverage, how many environments must be verified, and whether your team has a named owner for each plugin. Ask the provider to break the quote down by plugin and by upgrade cycle so you can see which items recur.

Duration depends on the plugin's dependency surface and the distance between your current Backstage release and the target. A plugin that only needs version alignment and a passing test run is a short task. A plugin that must move off a deprecated package, adopt a new backend or frontend system pattern, or change its tests is a larger one. No duration is given here because no researched figure applies to your codebase. Ask for a per-plugin estimate in the written scope, with the Backstage versions it covers and the test evidence you will receive before sign-off.

Your team needs to provide the plugin source, a working development environment, access to a non-production Backstage instance that matches production configuration, and a named reviewer who understands the business behavior the plugin supports. Your team also decides on acceptance criteria, such as which catalog entities, scaffolder actions or API calls must still work after the upgrade. Plan for a reviewer to be available during the test window, because a compatibility fix often changes behavior that only your domain experts can confirm.

Yes, many organizations do this in house, and the Backstage project publishes the upgrade tooling your team would use. Whether it is practical depends on whether you have engineers who know TypeScript, the Backstage plugin model and your CI pipeline, and whether they have time for the monthly release cadence. The Backstage versioning policy describes a main release line shipped monthly and a next line shipped weekly, so the work recurs. Compare the cost of a dedicated owner with a retainer that covers routine bumps and leaves larger changes to a fixed-scope project.

Patch when the plugin's logic is sound and the breaking changes are confined to imports, configuration or a small number of API calls. Rebuild when the plugin relies on internal behavior that no longer exists, when it duplicates a core feature that has since shipped, or when its tests cannot be trusted. As an illustrative example, a plugin that wraps a deprecated backend service may be cheaper to rewrite against the current plugin API than to patch line by line. Ask the provider for a short assessment of each plugin that recommends patch or rebuild with the reasons, before any build work is priced.

Ask for a written scope that lists each plugin, the starting and target Backstage versions, the packages and extension points in use, and the changes expected. Request the acceptance tests, the environments where verification happens, and the handover format, including updated documentation and pinned dependency versions. Ask what is excluded, such as new features, search engine changes or plugins that moved to the community repository, and whether a follow-up window is included for issues found after release. Also ask how future bumps will be priced if the work recurs.

Compatibility work and security work overlap but are not the same. The Backstage versioning policy says high and critical severity vulnerabilities will always be backported to releases from the last 6 months if feasible, and other security fixes may be backported. Your custom plugins still need their own dependency updates, code review and testing when those fixes arrive. Ask the provider whether security patch handling is part of the scope or a separate retainer item, and who approves a release that contains a security change.