Backstage Developer Portal: The 2026 Guide

The Backstage developer portal is the most adopted open-source framework for building internal developer portals, but it is also the most misunderstood. Teams hear that Spotify, Netflix, and American Airlines run on it and assume installing it will fix their service sprawl. Then they discover that Backstage is not a product you turn on. It is a TypeScript framework you assemble, host, and upgrade yourself, and the gap between starting and running it well is where most adoptions stall.

This guide explains what Backstage actually is, the four core concepts you need to understand before evaluating it, who it fits, the real operational cost, and the alternatives worth considering. If you arrived here unsure whether you need an internal portal at all, our wider developer portal guide covers the internal versus external distinction and the broader category. This piece goes deep on Backstage specifically.

By the end you will know whether self-hosted Backstage, a managed Backstage SaaS like Roadie, a proprietary portal like Port or Cortex, or no portal at all is the right next step for your engineering org.

What is the Backstage developer portal?

Backstage is an open-source framework, originally built at Spotify in 2016 and open-sourced in 2020, for assembling an internal developer portal. It is now a CNCF Incubating project with over 1,400 companies in its adopters list and a plugin ecosystem of more than 250 community-maintained integrations.

The shortest accurate description: Backstage is a Node.js and React application that gives platform teams the building blocks for a Software Catalog, technical documentation, and self-service templates, plus a plugin API for wiring in everything else (CI, Kubernetes, cloud accounts, observability, on-call). You install the framework into your own infrastructure, configure the plugins your stack needs, write or extend React components where the defaults do not fit, and operate the result like any other internal product.

Two important corrections to common misconceptions:

• Backstage is not "Spotify's developer portal." Spotify runs an internal fork with proprietary plugins. The open-source release is the framework, not the company's running portal.
• Backstage is not a SaaS product. There is no "sign in and configure" path. Adopting it means standing up a Node.js application backed by PostgreSQL.

The 2025 State of Internal Developer Portals report found platform teams spend 15 hours per developer per week on toil that a portal is meant to eliminate (Port, 2025). Backstage exists to remove that toil. Whether it does in practice depends heavily on the four concepts below.

The four core concepts of Backstage

Every Backstage conversation eventually turns into a debate about plugins, schemas, or upgrades. All of them sit on top of four primitives. Understand these and the rest of the framework makes sense.

1. The Software Catalog

The Software Catalog is the system of record. It is a graph of entities (Components, APIs, Resources, Systems, Domains, Groups, Users) defined in catalog-info.yaml files that live alongside your source code. The Backstage backend ingests these files through entity providers (the GitHub provider scans repos, the Kubernetes provider can synthesize entities from cluster resources) and renders the result as a browsable, searchable, queryable catalog.

A minimal entity looks like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  annotations:
    github.com/project-slug: company/payment-service
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: checkout
  providesApis:
    - payment-api

The catalog is where ownership, lifecycle, dependencies, and relationships live. Every other Backstage feature, from scorecards to templates to the on-call widget, reads from it. If the catalog is wrong, everything downstream is wrong, which is why catalog hygiene is the single biggest predictor of whether a Backstage rollout succeeds.

2. TechDocs

TechDocs is Backstage's "docs like code" feature. Engineers write Markdown alongside their service code, Backstage builds it with MkDocs under the hood, and the rendered docs appear inside the portal scoped to the matching catalog entity. If you have looked at the MkDocs Material theme, you have already seen the rendering layer that TechDocs uses.

The point of TechDocs is co-location. Documentation lives in the same repo as the code, ships through the same pull requests, and inherits the same code review. That solves the staleness problem for internal engineering docs. It does not, however, replace customer-facing product or API documentation. TechDocs is for the engineers building and operating services; it is not designed as a public surface for paying customers. We come back to this distinction later.

3. Software Templates and the Scaffolder

Software Templates are pre-defined skeletons that developers can use to create new services, libraries, or repos through a guided wizard. The Scaffolder is the engine that executes them. A template might create a new microservice repo with a baseline Dockerfile, CI workflow, observability hooks, owner metadata, and the matching catalog-info.yaml already in place.

The value is golden paths: instead of a new hire copying a five-year-old service and slowly diverging, they pick a template, fill in three fields, and end up with a repo that already meets the org's standards. Templates are where the platform team's impact shows up most visibly.

The catch: Backstage's Scaffolder concentrates on the "create" step. Day-two operations like environment promotion, deprecation, or migration usually require custom TypeScript actions or a separate orchestration tool.

4. The Plugin Architecture

Everything in Backstage, including the Catalog and TechDocs, is implemented as a plugin. Frontend plugins are React components registered through the extension API; backend plugins are Node modules that run as isolated services and communicate over the network.

The plugin model is what makes Backstage an ecosystem rather than a fixed product. The downside is that "installing a plugin" is a build-time composition step: you import an NPM package, register it in your app and backend, configure it, and redeploy. Plugins also evolve at their own pace, and breaking changes between major Backstage releases are normal. Plugin compatibility is the most common operational complaint in the r/devops Backstage threads.

Backstage vs other developer portals: the comparison

When teams evaluate Backstage, they are almost always also looking at a managed Backstage product (Roadie or Spotify Portal for Backstage) and one or two proprietary portals (Port, Cortex, OpsLevel). The right way to read the market is by who owns what.

Self-hosted Backstage gives you the most control and the lowest license cost. It also gives you the most work. Managed Backstage (Roadie or Spotify) preserves the open standard and the plugin ecosystem while removing the upgrade burden. Proprietary portals are usually faster to roll out but lock your service metadata into a vendor schema.

The honest framing: the choice is not about features. It is about who you want owning the data model and operational lifecycle in five years.

Who Backstage actually fits

Backstage is not a default. It is a heavy commitment that pays off in specific conditions and fails predictably outside them.

Strong fit signals:

• 100+ engineers with at least 50 services in production
• A funded platform engineering team of 3+ people whose job is the portal
• Strong TypeScript and React skills available for plugin work
• Heterogeneous tooling (multiple clouds, multiple CI systems) where a unifying catalog actually helps
• Leadership willing to treat the portal as a long-term internal product

Weak fit signals:

• Fewer than 50 engineers or fewer than 20 services
• No dedicated platform team, just "the SRE team will own it on the side"
• Homogeneous stack (one cloud, one CI, monorepo) where the value of unification is small
• Expectation that Backstage will be "installed in a week"

The 2025 State of Backstage report from Roadie shows the pattern clearly: organizations with dedicated portal teams report meaningfully higher satisfaction than those that treat Backstage as a side project. Understaffed Backstage rollouts are the most common failure mode, not bad architecture.

For smaller orgs, the right answer is usually to delay the portal and invest in internal documentation practices first. A good service README, a maintained team wiki, and a working CI pipeline cover 80% of what a junior engineer needs.

The real cost of running self-hosted Backstage

The license is free. The system is not.

A self-hosted Backstage deployment is a Node.js application, a React frontend composed from independently versioned packages, a PostgreSQL database, authentication and authorization wiring, secrets management, and a plugin set that drifts every month. Backstage releases monthly, on the Tuesday before the third Wednesday, and breaking changes are documented but not avoided. Staying current requires sustained attention.

Three specific costs that surprise teams:

1. Backend system migration. Backstage's new backend system reached stable 1.0 in 2024. For self-hosted teams this was a migration-class change: plugin registration moved from imperative to declarative backend.add() calls, the legacy @backstage/backend-common package was deprecated, and service-to-service communication shifted to dependency injection. Custom plugins needed updating; integrations needed re-validation.

2. Plugin API drift. A plugin you depend on (Datadog, PagerDuty, GitHub Actions) can break across Backstage majors. You are responsible for the patch.

3. Custom UI work. Anything beyond the default theme requires React engineering. Custom navigation, custom entity pages, custom scorecards, and custom dashboards all mean writing and maintaining components. Backstage gives you the canvas; you supply the painter.

The pattern that works: staff Backstage like any other production service. One platform engineer is not enough at scale. Three to five is realistic for an org with 200+ engineers. The pattern that fails: assume it is "just a portal."

Backstage TechDocs vs external product documentation

This is where teams using Backstage often hit a second documentation problem. TechDocs is excellent for internal engineering docs (service READMEs, runbooks, architecture notes) but it is not the right tool for the docs your customers read. The audiences, the conventions, and the publishing model all differ.

Internal engineering docs live next to code, get reviewed in pull requests, and target colleagues who can read TypeScript. Customer-facing product and API documentation targets people who often cannot, gets indexed by search engines, has its own brand and design system, and ships on a different release cadence than your services. Trying to make TechDocs do both ends up with a portal page that looks fine to engineers and confusing to everyone else.

Most Backstage adopters end up running a separate external docs surface alongside their portal. That is where tools like Docsio fit: external product and API docs generated from your existing site, with brand matching and a separate hosted surface, while Backstage handles the internal engineering catalog and TechDocs. They solve different jobs for different readers and rarely overlap.

For the broader category of customer-facing portals (API consoles, SDK downloads, changelogs), see our API portal and documentation portal guides.

Backstage alternatives worth evaluating

If self-hosted Backstage looks too heavy for your team, four options are worth a real evaluation rather than a glance.

Roadie. Managed Backstage SaaS. You get the open standard, the plugin ecosystem, and the entity model without operating the framework. The tradeoff is per-developer pricing instead of free, and a vendor sits between you and the upstream codebase.

Spotify Portal for Backstage. Spotify's commercial managed offering, launched 2024. Adds premium plugins (Soundcheck for tech health, Insights for usage analytics, Skill Exchange, AiKA AI assistant) on top of a managed Backstage core. Strongest fit if you want Spotify's opinions baked in.

Port. Proprietary internal developer portal with no Backstage lineage. Faster to roll out, opinionated about the catalog model, and visible in the SERP because they publish heavily on the category. Tradeoff: your service metadata lives in their schema.

Cortex and OpsLevel. Both lean on scorecards and service maturity scoring. Strong fit if your problem is "we have services but no consistent quality bar," weaker fit if your problem is "we have no catalog at all."

The wrong way to pick: feature checklist. The right way: who do you want owning your service catalog data model in three years? Self-hosted Backstage answers "we do." Managed Backstage answers "us, on the open standard." Proprietary portals answer "the vendor."

Backstage tutorial: the realistic path to first deploy

If you have decided Backstage is the right call, here is the abbreviated rollout that matches what teams who have done it well actually do. The Backstage docs cover the technical steps; this is the human sequence.

1. Staff first, install second. Identify the platform engineers who will own the portal. Without dedicated owners, skip to picking a managed option.
2. Run npx @backstage/create-app and stand up the default app locally. This is the cheap step. You will throw away most of the default configuration, but it gives the team something concrete to react to.
3. Pick one team and one service to onboard end-to-end. Add a catalog-info.yaml, wire up TechDocs, integrate one CI plugin. Resist the urge to onboard everything at once.
4. Decide on auth and deployment. SSO via your IdP, PostgreSQL backing the catalog, deployment on Kubernetes or a managed Node host. Get this stable before scaling.
5. Define what "ready" means before opening it up. Three plugins working reliably and one team using the portal daily beats twelve plugins half-configured.
6. Schedule the upgrade cadence. Backstage releases monthly. Decide whether you track every release, every quarter, or every major. Then stick to it.

Skipping step one is the single most common reason rollouts fail. Skipping step five is the most common reason they stagnate.

Why developers will or will not use the portal

A portal that nobody opens is a budget line, not a product. The patterns that drive adoption are the same in Backstage as in any other internal tool, and they are uncomfortably product-flavored.

• The catalog is accurate and current. Stale ownership kills trust within two weeks.
• One workflow is genuinely faster through the portal than through the old tool. New service creation is the usual winner.
• Documentation through TechDocs is searchable and finds answers. If search returns nothing useful, the portal becomes shelfware.
• Leadership uses the portal in meetings. Top-down usage drags bottom-up usage.

The flip side, covered in our piece on why developers don't read documentation, applies to portals too. Engineers route around tools that waste their time. A portal earns daily use the same way a docs site does: by being faster than the alternative.

Frequently asked questions

What is the Backstage developer portal?

Backstage is an open-source framework, built by Spotify and open-sourced in 2020, for assembling an internal developer portal. It provides a Software Catalog, TechDocs, Software Templates, and a plugin system that platform teams use to centralize service ownership, documentation, and self-service workflows for their own engineers.

Is Backstage free?

The open-source framework is free under the Apache 2.0 license. The real cost comes from running it: the engineering time to host, configure, upgrade, and maintain a Node.js application plus PostgreSQL database, and the plugin-level customization needed to fit your stack. Managed options like Roadie and Spotify Portal for Backstage charge per developer.

Who uses Backstage?

Public adopters include Spotify, Netflix, American Airlines, Expedia, Mercedes-Benz, and over 1,400 other organizations listed in the official adopters file. The common pattern across them is engineering orgs above 100 developers with a funded platform team. Backstage is rarely a good fit below that threshold.

Backstage vs Port: which should I pick?

Pick Backstage if you want to own the data model and have engineers who can run the framework. Pick Port if you want a faster rollout and are comfortable with a vendor-defined schema. The decision is mostly about who owns the catalog model long-term, not about which tool has more features today.

Can Backstage replace customer-facing product documentation?

No. TechDocs is designed for internal engineering documentation that lives next to service code. Customer-facing product and API docs target different readers, need SEO and brand control, and ship on a different release cadence. Most Backstage adopters run a separate external docs surface for customers alongside their internal portal.

The verdict

Backstage is the strongest open standard for internal developer portals, and for the right org it is the right pick. The right org is one with 100+ engineers, a funded platform team, real TypeScript skills, and the patience to treat the portal as a long-term product. For everyone else, the honest recommendation is to delay: ship better READMEs, tighten up your internal wiki, and revisit Backstage when the catalog problem actually hurts.

For external product and API docs, Docsio generates a branded documentation site from your existing website in under five minutes, with an AI agent that handles edits and one-click publish to a custom domain. It is the complement to a Backstage portal, not a replacement, and it covers the customer surface that TechDocs was never built for. Start free and have your customer-facing docs live before the platform team has finished evaluating IDPs.