Backstage

What it is

Backstage is an open-source platform created by Spotify and donated to CNCF for building unified developer portals. It functions as an extensible framework that centralizes tools, services, and documentation in a single web interface, enabling engineering teams to create customized internal developer platforms.

The platform is built on a plugin architecture that allows integration of any tool in the development ecosystem — from CI/CD systems to observability dashboards. Unlike commercial solutions like Port or Cortex, Backstage offers complete control over the developer experience, but requires significant investment in development and maintenance.

Its adoption has grown exponentially since open-sourcing in 2020, especially in organizations with more than 100 developers that need to standardize processes and improve developer experience.

Core components

Software Catalog

The catalog is Backstage's heart, providing a centralized inventory of all software components. Each entity is described through catalog-info.yaml files that define metadata, owners, and relationships:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: User management microservice
  annotations:
    github.com/project-slug: company/user-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-backend
  system: user-management
  providesApis:
    - user-api
  consumesApis:
    - auth-api
  dependsOn:
    - resource:user-database

Software Templates

Templates enable creating new projects following organizational golden paths. They use the Cookiecutter templating engine to generate code, CI/CD configuration, and initial documentation:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-microservice
  title: Node.js Microservice
  description: Template for creating a Node.js microservice with TypeScript
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Information
      required:
        - name
        - owner
      properties:
        name:
          title: Name
          type: string
          pattern: '^[a-z0-9-]+$'
        owner:
          title: Owner Team
          type: string
          ui:field: OwnerPicker
  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./template
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}

TechDocs

Documentation-as-code system that renders Markdown in the Backstage interface. It integrates with Git repositories to keep documentation synchronized with code:

# mkdocs.yml
site_name: 'User Service Documentation'
nav:
  - Home: index.md
  - API: api.md
  - Deployment: deployment.md
plugins:
  - techdocs-core

Plugin development

Backstage uses a microfrontend architecture where each plugin is an independent npm package. Plugins can contribute pages, components, and hooks to Backstage's core:

// plugins/cost-insights/src/plugin.ts
import { createPlugin, createRoutableExtension } from '@backstage/core-plugin-api';
 
export const costInsightsPlugin = createPlugin({
  id: 'cost-insights',
  routes: {
    root: rootRouteRef,
  },
});
 
export const CostInsightsPage = costInsightsPlugin.provide(
  createRoutableExtension({
    name: 'CostInsightsPage',
    component: () => import('./components/CostInsightsPage').then(m => m.CostInsightsPage),
    mountPoint: rootRouteRef,
  }),
);

Comparison with alternatives

Architecture and deployment

Why it matters

Backstage represents a fundamental shift in how organizations approach developer experience at scale. For staff+ engineering teams, it's the difference between having dozens of scattered tools and a unified platform that reduces cognitive load and accelerates onboarding.

ROI materializes in three areas: reduced discovery time (from hours to minutes to find APIs and documentation), process standardization (templates that ensure compliance from day one), and organizational visibility (clear health metrics and ownership). However, it requires significant upfront investment — typically 2-3 FTEs for implementation and 1-2 FTEs for ongoing maintenance.

The decision to adopt Backstage versus commercial alternatives depends on the trade-off between control/customization and time-to-market. Organizations with specific integration needs or strict data policies tend toward Backstage, while teams prioritizing initial velocity opt for SaaS solutions.

References

• Backstage Software Catalog and Developer Platform — Spotify, 2020. Official site and documentation.
• What is Backstage? | Backstage Software Catalog and Developer Platform — Backstage Team, 2024. Official conceptual guide.
• Backstage Software Catalog | Backstage Software Catalog and Developer Platform — Backstage Team, 2024. Software catalog documentation.
• TechDocs Documentation | Backstage Software Catalog and Developer Platform — Backstage Team, 2024. Documentation-as-code guide.
• What the Heck is Backstage Anyway? | Spotify Engineering — Stefan Ålund, 2020. Original history and motivation.
• Maximizing Developer Effectiveness — Tim Cochran, 2021. Context on developer productivity.
• GitHub - backstage/backstage: Backstage is an open framework for building developer portals · GitHub — Backstage Community, 2024. Official repository and roadmap.