Backstage: The Developer Portal Framework

Why it exists

Engineering organizations that adopt microservices and cloud native tooling eventually hit a wall of fragmentation. A single developer might need to open ten different browser tabs to find a service owner, read an API spec, check CI status, view runbooks, and submit a support ticket. Backstage was created to solve this discovery and context problem by providing a single, extensible home for all engineering resources.

The mental model

Think of Backstage as an operating system for your engineering organization, not a shrink-wrapped application. It is a framework that you extend with plugins and populate with metadata to build a developer portal unique to your company. The core abstraction is the Software Catalog, a graph of entities such as services, APIs, resources, systems, and domains that models your real world architecture.

How it works

Teams define entities in YAML files that live next to source code, typically in a repository. Backstage ingests these definitions to build the catalog, tracking ownership, dependencies, and lifecycle. The frontend is a React application that renders plugins. Each plugin talks to existing infrastructure, such as Kubernetes, Jenkins, GitHub, or PagerDuty, surfacing that data in the portal without replacing the underlying tool. This means Backstage aggregates and displays; it does not execute builds or host workloads itself.

When to use it

Adopt Backstage when you have dozens of services and multiple teams that struggle with discoverability, onboarding, or standardization. It excels when you want to enforce golden paths, such as scaffolding a new service from a template with CI, observability, and documentation already wired in. It is also valuable when you need a single pane of glass for operational data that currently lives in silos.

When not to use it

Do not reach for Backstage if you are a small team with a handful of repositories and no dedicated platform team. The upfront cost of deployment, plugin development, and metadata curation will outweigh the benefits. It is also a poor choice if you expect an out-of-the-box product; Backstage requires significant customization and ongoing maintenance to remain useful.

One canonical example

Spotify built Backstage internally to manage thousands of microservices. A developer visiting a service page in Backstage can see the owning squad, read TechDocs generated from markdown in the repo, view current CI status, check the on-call rotation from PagerDuty, and discover upstream and downstream dependencies, all without switching contexts. This consolidation turns tribal knowledge into searchable, structured context.