Backstage migration to new backend and frontend systems

What a Backstage migration involves

This page covers two kinds of migration work. The first moves an existing Backstage app from the legacy backend and frontend wiring to the new backend and frontend systems, which means reworking the app's entry points, plugin registration and configuration loading. The second imports catalog data from a wiki, a service registry or a spreadsheet into the Software Catalog, where the work is mapping existing records onto entity kinds, owners and relationships. Both can happen in the same project, but they carry different risks, so plan them as separate workstreams.

Teams usually start this work for one of four reasons. A planned version upgrade stalls because legacy wiring in the app does not map cleanly to the new systems. Custom plugins that were written against the old APIs block the move until someone ports or replaces them. Several separate portals need to be consolidated into one catalog. Or the service inventory lives in spreadsheets and wiki pages that nobody trusts enough to load as-is. Each trigger points to a different first task, so name the trigger before estimating anything.

On in-house versus partner work, a team with Backstage and TypeScript experience can often run a small catalog import itself, since the work is mostly data mapping and validation. Custom plugin wiring and the live cutover are where partners are most often engaged, because they touch production authentication, routing and data paths at the same time. Ask any partner to show how they will keep the old portal running in parallel and how they will roll back if the cutover fails.

Routine version upgrades on the monthly main release line and the weekly next line are covered on the upgrades page, so this section does not repeat that cadence. Before you request a quote, confirm which Backstage version your app currently runs, list every custom plugin and whether it has been updated for the new systems, and confirm where the source inventory lives and who owns its accuracy.

What the work includes

A fixed-scope migration produces the artifacts below. The exact list, formats and acceptance criteria are agreed in writing before work starts.

Legacy wiring inventory

A written inventory of how the current app is wired: legacy backend and frontend entry points, custom plugins, catalog sources, processors, auth providers and integration tokens. Each item is marked as moved, replaced or retired. Ask for owners of each plugin to review it before design starts, since owner sign-off is where missed dependencies usually surface.

Target design and migration plan

The target architecture for the new backend and frontend systems, with decisions on plugin registration, configuration layout and which legacy patterns are kept. The plan sequences the work into stages, names blocking dependencies and sets the order in which plugins move. Check that every deferred item has a named owner and a revisit date.

Migrated code on a branch

The migrated backend and frontend code, delivered on a branch in your repository, with commits that map back to inventory items. The branch builds in your standard CI pipeline and includes updated configuration for each environment. Confirm who reviews and merges it, and how the branch is kept current while the cutover is scheduled.

Catalog import pipeline and validation reports

A repeatable pipeline that moves entities from your wiki or service registry into the Backstage catalog, with mapping rules for owners, lifecycles and relations. Each run produces a validation report listing rejected entities, missing owners and duplicate names. Ask how reports are reviewed and who corrects source data before the final import.

Staged cutover and rollback runbook

A runbook for moving users and traffic in stages, with entry and exit criteria, switch steps and rollback steps for each stage. It includes test evidence from each environment, so the go or no-go decision rests on recorded results rather than memory. Confirm who signs off each stage and how long a rollback window stays open.

Handover documentation for the platform team

Operating documentation for the team that will run the app after handover: architecture notes, a configuration reference, upgrade steps, runbooks for common failures and ownership records. The platform team should be able to perform a routine upgrade from these documents without the migration engineers. Confirm the document format and where it will be stored.

What drives cost and duration

This table lists the main factors that change the effort of a Backstage migration, why each one matters, and what keeps it manageable.

Driver	Why it matters	How to keep it down
Custom plugins and legacy wiring points	Each custom plugin and hand-wired registration must be re-expressed in the new systems, and each one can change behavior without an obvious error.	Inventory plugins and wiring before estimating. Retire unused plugins and move to supported extension points early.
Sign-in providers and resolvers to preserve	Each provider and resolver maps users to identities, so a mismatch can lock people out or create duplicate user entities.	List every provider and its resolver, confirm identity mapping in staging, and remove guest access before cutover.
Catalog sources and entity volume	Each location, provider or ingestion path adds processing time and a point of failure, and entity count drives load during the first full sync.	Count sources and entities at scoping, consolidate overlapping providers, and load in batches so results can be compared.
Data quality and ownership accuracy	Missing owners, stale catalog-info.yaml files and wiki pages without owners make the migrated catalog look complete when it is not.	Run ownership and orphan reports before migration, confirm owners with each team, and agree a rule for entities without owners.
Environments and users during cutover	Parallel environments, staged user groups and rollback paths multiply testing and support work, especially while teams still use the old portal.	Limit the number of environments in the cutover, choose a pilot group, and agree the rollback window in writing.
TechDocs and search state	Documentation sites and search indexes must be rebuilt or re-pointed, and a stale index returns old or missing results.	Decide what is regenerated and what is carried over, rebuild docs in the target storage, and check search against a fixed test list.
Distance between current and target release	A larger gap between the current and target Backstage release means more template changes, codemods and plugin version conflicts to resolve.	Bring the current app to a recent release first, review template changes with the Upgrade Helper, and confirm Node.js support for the target release.
Compliance evidence requirements	Assessors may ask for records of access changes, ownership decisions, test results and cutover approvals, which adds documentation work.	Agree the evidence list at scoping, capture change records during the work, and confirm requirements with your assessor.

Project phases and outputs

The sequence moves the existing app and its catalog data across in checked stages, so each phase produces evidence that the next one depends on.

Inventory wiring, catalog sources and plugins
We review the existing app's legacy backend and frontend wiring, every catalog source (files, providers, wiki or registry feeds) and each installed plugin with its owners. The output is a written inventory that marks each item as carry over, rewrite, replace or retire, reviewed with your platform team.
Design the target and pin a release line
We map each inventory item to its place in the new backend and frontend systems and agree which Backstage release line the migration targets. The output is a design note and a pinned version, so the team knows exactly what it is migrating to before any code changes.
Spike one plugin and one catalog source
We migrate one representative plugin and one catalog source end to end in a throwaway branch. The spike is complete when it runs locally and the entities it produces match the expected owners and relationships, and the findings are used to adjust the plan.
Build the migration in parallel on a branch
The remaining plugins, wiring and catalog sources are migrated on a long-lived branch while the current portal stays in production. The output is a buildable branch with a short list of open issues, reviewed against the inventory so nothing is dropped silently.
Run catalog import dry runs with validation reports
We run the catalog import against a copy of production data as repeated dry runs, fixing ingestion errors and ownership gaps each time. Each run produces a validation report listing missing owners, orphaned entities and changed references, and the phase closes when the report is clean or each remaining item is signed off by its owner.
Cut over in staged environments with a rollback path
The migrated app is deployed to a non-production environment for functional and sign-in checks, then to production in a planned window. Before cutover we document the rollback steps and rehearse them, so the team can return to the previous deployment if a check fails.
Hypercare and handover
After cutover we watch errors, catalog ingestion and plugin behavior closely for an agreed period and fix issues as they appear. The phase ends with a handover pack covering runbooks, the validation history, the upgrade path and open items, accepted by your team.

What stays in-house and what goes to a partner

This table shows who usually owns each part of a Backstage migration and the skills each part requires, so you can decide where your own team leads and where a partner adds capacity.

Work part	Who usually owns it	Skills required
Inventory and decision log	In-house, with partner review	Backstage architecture knowledge, plugin and integration inventory, decision records, change management
Catalog data mapping and owner confirmation	Platform team with data owners	Catalog model design, entity YAML and provider configuration, data ownership processes
Custom plugin and scaffolder wiring	Partner or senior Backstage engineers	TypeScript, Node.js, Backstage plugin and scaffolder APIs, the Backstage CLI
Auth and sign-in resolver checks	Identity team with the partner	Identity protocols such as OIDC and SAML, group claims, resolver testing, removing guest access
Staged cutover and rollback rehearsal	Shared by platform team and partner	PostgreSQL operations, deployment pipelines, change management, incident coordination
Post-cutover ownership	Platform team	Upgrade routine, Node.js support windows, PostgreSQL operations, on-call and change management

What usually goes wrong

Most failed Backstage migrations break in a small set of predictable places. Each pattern below names the symptom, the cause and the staged check that catches it before production users notice.

Catalog ownership drift

Entities imported from a wiki or service registry often arrive with owners copied from stale records, so teams see components they do not run. Confirm each owner with the team lead before import, and set an acceptance check that every imported component resolves to a current group in the catalog.

Sign-in regressions from resolver changes

Editing sign-in resolvers during wiring work can map the same person to different identities, or break login for one provider. Keep resolver changes in their own reviewed change set, and run a written sign-in test for each configured provider in the staging environment before cutover.

Plugin incompatibility with the target release

Community and custom plugins may still use the legacy wiring or lag behind the @backstage packages you move to. Inventory every plugin, record its version and migration status, and block cutover until each one builds and starts in staging against the target release.

Cutover without a tested rollback

A cutover plan that describes only the forward path leaves the team improvising when the new backend misbehaves. Write the rollback steps, including how the catalog database and TechDocs storage return to the prior state, and rehearse them in staging before the production window.

Node.js version mismatch

Backstage supports exactly two adjacent even-numbered Node.js releases, which as of Backstage 1.46.0 are Node.js 22 and 24. Pin the runtime in your build images and CI to a supported pair, and verify the version in the staging container matches the one used for the release build.

Stale TechDocs and cache state

After cutover, documentation may show old builds and cached catalog responses may serve pre-migration data. Plan a TechDocs rebuild and a cache flush as explicit steps, then check a sample of pages and entities against the source repositories as part of the acceptance checklist.

Migration stopped halfway

When a migration pauses with some entities in the old system and some in the new one, teams cannot tell which catalog is authoritative. Set a named system of record and a dated freeze on the legacy source before the first import, and treat any unfinished batch as a blocker for go-live.

How the work differs by starting point

The app runs a current Backstage release but still registers plugins and catalog providers through the legacy wiring. Scope is narrower because the framework code is already recent, so the work centers on moving startup code and plugin registration.

Scope: move backend plugin registration and frontend app composition to the new systems, one plugin at a time.
Effort: driven mostly by the number of custom wiring files and how many plugins expose their own routes.
Risk: duplicate registrations or routes that resolve differently during cutover.
Confirm: the exact release in use, the Node.js version on build and runtime hosts, and whether any plugin still lacks a new-system export.

What your team needs to provide

Start with access and an inventory, because they determine how much of the early work goes to discovery. Provide read access to the existing Backstage repository, deployment manifests and CI pipeline, plus a way to run the app locally. Then provide a list of every installed plugin, every custom plugin and every catalog source, whether that is a catalog-info.yaml file, a provider, a wiki export or a service registry. Each undocumented plugin or source adds analysis time, which the quote should reflect.

Name an owner for each catalog domain who can confirm entity data for components, systems, APIs, resources and groups. Migration carries ownership fields into the new system, so an owner who can answer whether a component is still running keeps dead records out of the catalog. Also provide a non-production environment that matches production in database engine, authentication configuration and catalog sources. If the environment differs, cutover rehearsals test the wrong behavior and the team repeats them.

Provide the sign-in provider details, including the provider type, the tenant or organization, and the group claims you expect. Decide the sign-in resolver expectations early: which identifier maps a user to a catalog entity, and what happens when that match fails. The Backstage authentication documentation advises configuring resolvers so every provider resolves to the same identity and not offering guest access in production. Also name a change freeze window for cutover that covers catalog sources, plugin configuration and identity settings, since changes during the window force the rehearsal to start over.

Name the decision makers who can approve trade-offs during the build. These include whether each plugin is kept, replaced or retired, which legacy catalog source becomes the system of record for each domain, and who signs off the cutover. An open decision blocks the work that depends on it, so a question that waits for a steering meeting adds calendar time. Ask for these names in writing with a response expectation, and confirm the assumptions behind the schedule with DeployOpen against your environment before the fixed-scope quote is signed.

Common questions about Backstage migration

How is a migration different from a regular Backstage version upgrade?

A version upgrade moves an existing app to a newer release of the same wiring, usually by bumping the @backstage packages together and applying template changes. A migration changes how the app is wired: plugins and startup code move from the legacy backend and frontend setup to the new system, and catalog data is often brought in from a wiki or service registry. Because the code structure changes, a migration touches more files, more plugins and more of the test suite. Plan it as its own project with a defined cutover window.

What drives the cost and timeline of a Backstage migration?

The main drivers are the amount of custom code and the number of plugins that must be rewired, the number of catalog sources to import, and how much authentication and TechDocs setup is involved. The number of environments, whether staging mirrors production, and how many teams rely on the portal during cutover also matter. Costs come from scoping and migration work, which is largely one-time, plus the internal time your engineers spend on reviews and testing. Ask for a written scope that lists each plugin, catalog source and environment, with a deliverable for each phase. DeployOpen does not publish prices, so the written scope sets the numbers.

What does our team need to provide during a Backstage migration?

Your team supplies access, decisions and people's time. Name an owner who can approve scope and sign off each phase, and provide read access to the repository and CI system. You will also need a staging environment that resembles production and the identity provider details used for sign-in. Engineers who know the custom plugins and the ownership data in the catalog are needed for reviews and test sign-off. Someone must agree on the cutover window and on which teams are told when the portal is unavailable. Confirm these commitments in the written scope so the schedule has named owners.

Can a small platform team import its catalog without outside help?

A small team can often import catalog data alone, especially when the source is a single wiki or registry with consistent fields. The harder work is mapping ownership, deciding which entries become components, systems, APIs or resources, and removing duplicate or stale records before they reach production. Start with a pilot group, validate ownership with the teams involved, and keep the import repeatable so it can run again at cutover. Outside help is most useful for the mapping design and the staged rollout, where mistakes reach every team that depends on the catalog.

How does rollback work during a staged Backstage cutover?

Rollback means keeping the legacy setup runnable until the new system passes defined checks for each group of users or plugins. Teams usually route a limited group to the new backend and frontend first, keep the catalog import repeatable, and retain database backups taken before the switch. Rollback is simplest when the legacy deployment and its configuration are kept in version control and can be redeployed without a rebuild. Confirm in the written scope which checks trigger a rollback, who can make that decision, and how long the legacy stack stays available.

What do we receive at the end of a Backstage migration engagement?

A completed engagement delivers a migrated Backstage app running in your infrastructure, with the cutover completed or staged as agreed and the catalog data imported and validated. Expect source changes committed to your repository, updated configuration and deployment manifests, a test record, and runbooks for operating and rolling back the portal. Documentation should cover plugin decisions, catalog mapping rules and the owners of each component. The exact list is defined by the written scope, so review each deliverable and its acceptance criteria before work starts.

How DeployOpen runs Backstage migrations

DeployOpen plans and carries out Backstage migrations to the new backend and frontend systems in infrastructure you control, including catalog data moved in from a wiki or service registry. The work moves in stages so each cutover can be checked before the next one starts.

How we scope

Inventory the existing app's backend plugins, frontend wiring, custom packages and catalog sources before any code changes.
Record which plugins have new-system equivalents, which need rework and which are retired, in the written scope.
Agree the cutover stages, rollback points and acceptance checks in writing, since engagements are fixed-scope.

How we build

Migrate the backend and frontend wiring in a branch, keeping plugin behavior and existing routes unchanged where possible.
Map catalog data from the wiki or service registry into entity definitions and check ownership fields against source records.
Test sign-in resolvers, database connections and TechDocs builds in a staging environment that mirrors production configuration.

How we hand over

Deliver a cutover runbook covering each stage, its verification steps and the rollback procedure for that stage.
Document the migrated architecture, configuration files and any custom code so your platform team can maintain it.
Walk through the final state with your team and confirm which items remain open after the cutover.

How we support

Offer post-cutover support, upgrades and continuous testing as a retainer if your team wants ongoing help after handover.
Plan upgrade work around the Backstage release lines and Node.js versions your organization has approved.
Confirm with your team, before signing, what support window, response expectations and scope the retainer covers.

Backstage migration to the new backend and frontend systems