Backstage: Spotify’s Developer Portal

Actualizado: 2026-05-03

Backstage^[1], open-sourced by Spotify in 2020, is the most-used foundation for building Internal Developer Platforms (IDPs). It has consolidated as the industry reference — adopted by Spotify, American Airlines, Netflix, Roku, and hundreds of other organisations. It’s not a closed product: it’s an extensible platform each organisation adapts. We cover how it works, what you get out of the box, and the adoption costs rarely mentioned in conference talks.

Key takeaways

• Backstage is a Node.js + React web application acting as a single portal for services, docs, scaffolding, and search.
• The software catalog is the core: each entity is described in YAML and relationships are inferred automatically.
• The scaffolder turns the “golden paths” promise into reality — but each template is code that needs maintenance.
• For organisations with fewer than 30-50 developers, the investment rarely pays off.
• Adopting it properly requires 1-3 dedicated engineers for months, not a weekend project.

What It Really Is

Backstage is a web application (Node.js + React) acting as a single portal for everything a developer needs at work. Five main building blocks:

• Service catalog: centralised inventory of what exists, who maintains it, and its dependencies.
• Plugins: each additional function — CI/CD status, Kubernetes, monitoring, docs, cloud costs — comes as a pluggable plugin.
• Scaffolder: new-component generator from standard templates.
• TechDocs: documentation as code, rendered inside the portal.
• Search: federated search over all of the above.

The vision is a single place where the developer finds what exists, how to create new things, where the docs are, and what’s happening with their services.

Software Catalog: The Heart

Each entity in Backstage is described by a simple YAML:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: orders-api
  description: Service that manages purchase orders
spec:
  type: service
  lifecycle: production
  owner: team-orders
  system: ecommerce

Main entity types: Component (services, libraries, websites), API, Resource (DBs, queues), System (groupings), Group (teams), User, Domain (functional areas).

Relationships are inferred from YAML: “this component belongs to system X, its API is consumed by Y, it’s in domain Z”. Backstage builds a navigable network of the whole architecture. The catalog is fed by three sources:

• Locations (URLs of YAMLs) — can live in each service’s repo or centralised.
• Providers that automatically discover entities (Kubernetes cluster, GitHub orgs, etc.).
• Manually via the web interface.

Plugins: Where the Ecosystem Lives

Backstage is only useful with plugins. The most important in practice:

• GitHub / GitLab: see repo, PRs, and contributors directly in the portal.
• CI/CD: build, deploy, and run status (Tekton, ArgoCD, Jenkins, GitHub Actions).
• Kubernetes: see pods, deployments, and events for the current component.
• TechDocs: markdown documentation inside the portal.
• PagerDuty / Opsgenie: current oncall for each service.
• Datadog / Grafana / NewRelic: embedded component dashboards.
• Cost Insights: cloud cost per service.

There are 100+ official and community plugins. Building your own is a React exercise plus a couple of config files.

The Scaffolder: Golden Paths in Action

The scaffolder is where Backstage turns the platform engineering promise into reality. You define templates that generate at once:

• New GitHub repository with standard structure.
• Configured CI pipeline.
• Kubernetes manifests with resource limits and health checks.
• Pre-created Grafana dashboard.
• Basic alerts.
• Catalog entry pointing to the new component.

All from a web wizard where the developer fills in few fields (name, team, type). What would take hours or days manually, takes minutes.

Implementing this requires real investment: each template is code (YAML + shell + Backstage actions), and maintaining it as internal conventions change is ongoing work — not a one-off project.

TechDocs: Docs as Code

TechDocs renders markdown from the service’s own repo inside the portal. Documentation lives with the code, updates in the same PRs, and is seen with good UX in a centralised place.

Internally it uses MkDocs as the rendering engine. Integration is simple: add a mkdocs.yml and docs/ folder to the repo, reflect in catalog-info.yaml, and it appears in Backstage. It’s one of the most adopted features because it solves a real problem: documentation scattered across Confluence, wikis, READMEs, and PDFs.

The Real Cost of Adopting Backstage

Conference talks sell Backstage as “install and ready”. The reality of seriously implementing it has five cost components:

1. Dedicated team. Adopting it well requires 1-3 full-time engineers for months for configuration, plugins, and migration.
2. Continuous investment. Plugins evolve, integrations change, templates need maintenance. It’s not a “project” — it’s an internal product.
3. React/Node.js learning curve. If your team is backend-heavy, adopting the Backstage frontend is a new skill.
4. Data in good state. If your current inventory is an outdated spreadsheet, Backstage won’t fix it — only expose it.
5. Cultural adoption. Developers must go to the portal, maintain their catalog-info, write TechDocs. Without organisational push, it’s underused.

For organisations with fewer than 30-50 developers, the investment rarely pays off. For larger ones, ROI can be substantial — but requires real commitment, not a Friday project.

Alternatives and Managed Options

Backstage isn’t the only option:

• Port^[2]: managed SaaS with catalog and portal, less flexibility but zero operations.
• Cortex^[3]: similar, focus on service catalog and maturity scorecards.
• Roadie and Spotify Portal for Backstage: managed Backstage version by external companies.
• Custom build: for organisations with very specific stack, sometimes a custom dashboard works better.

Conclusion

Backstage is the default choice if your organisation has the scale and commitment to build a serious IDP. Its flexibility is its strength and its demand: it forces you to make decisions other more opinionated tools resolve for you. If you get the investment and organisational backing right, the result is valuable. If you treat it as “install Backstage on Fridays”, it’ll end up half-done.

1. Backstage
2. Port
3. Cortex