Backstage Adoption Guide: When to Use Spotify's Developer-Portal Framework

If you’ve spent more than five minutes in the platform engineering Slack, you’ve heard about Backstage. It’s the open-source darling of internal developer portals (IDPs), claiming 67% of the market and promising to tame the chaos of microservices with a single pane of glass.

For many teams, Backstage has been a huge win. But here’s the catch: building a production-ready IDP is a serious investment. Some teams abandon the effort halfway, while others celebrate gains in productivity and DevEx.

I wanted to know why Backstage clicks for some organizations but falls flat for others, so I spoke with 20 engineering teams—from scrappy startups to global enterprises—who’ve lived the Backstage life. They shared what worked, what didn’t, and what they wish they’d known before starting.

This guide distills their advice into practical tips you can use to decide whether Backstage is the right move for your team, and how to make your IDP initiative a success… without burning months of engineering time.

Backstage in 60 Seconds

At its core, Backstage is a service catalog. A single place where developers can find details about every microservice and component: docs, ownership, dependencies, onboarding steps, and more.

On top of that, Backstage offers two big draws:

• Scaffolder: Templates for spinning up new services with best practices baked in.
  
• Plugins: From scorecards to security checks (and plenty of custom ones you’ll probably definitely end up writing).

Interestingly, not every team uses the service catalog. For some, the scaffolder was the only feature they needed, and it delivered enough value on its own.

A word of caution: where you start can make or break your initiative. Roll out too much at once, and you’ll burn cycles on unclear value and confused users. Make sure you have a sharp focus and a clear ROI argument before you start. As one user put it:

“Don’t try to pull in every Backstage tool at once. Start with one (catalog, docs, or scaffolder), roll it out, get feedback, then add the next.” — Zeshan Ziya (Axelerant)

When Backstage Makes Sense (and When It Doesn’t)

Backstage isn’t a silver bullet. It only pays off when it fits your org’s size, culture, and appetite for DIY, and when it’s pointed squarely at a real pain (microservice sprawl, onboarding drag, inconsistent templates, tool sprawl, etc.). Use this quick test to self-qualify before you commit.

Backstage makes sense if:

• You’ve got scale pain: Multiple teams and dozens (or hundreds) of services mean nobody can answer “who owns what?” without a hunt.
  
• You want a developer-first home base you can deeply tailor with custom plugins, processors, and data enrichments
  
• You can spare ~3–5+ engineers to build & maintain it.
  
• You have (or can get) top-down support from management to encourage (or require) usage of your IDP
  
• Your paved-road / golden-path story primarily targets new services as opposed to existing, legacy services
  
• Your culture tolerates iterative rollouts & experimentation: start with catalog or onboarding, prove value, expand
  
• You want docs that live with code (i.e. markdown files managed with source control alongside services)

Backstage may not be right if:

• You’re a very lean org (< ~30 - 40 engineers) or have only 1 (or zero) part-time maintainers
  
• You expect a turn-key developer portal that works out-of-the-box
  
• Your platform/SRE team has zero frontend/TypeScript capacity (and no budget to add it)
  
• You primarily want leadership dashboards (Scorecards, DORA metrics, etc) as opposed to a developer-first homepage
  
• You lack executive backing (the “build it and they will come” story rarely works for Backstage)
  
• You don’t have 6-12 months to properly build your IDP and get it widely adopted
  
• You’re already entrenched in DIY solutions that aren’t worth replacing with Backstage

“We already built so much DevEx infra that was highly specific to our company. We tried retrofitting Backstage, but at that point it was just a UI layer and it didn’t seem worth it.” — Yeshwanth Shenoy (Okta, ex-Rakuten)

Rule of thumb: If the time you’re currently wasting finding owners, bootstrapping infra, or re-explaining onboarding materials easily adds up to a few engineer-months a year, Backstage can pay for itself. If not, start lighter, or consider using a vendor.

Is Backstage Free?

“The homepage literally says ‘an open-source framework for building developer portals’. It doesn’t say ‘a free developer portal.’ You still have to build the thing.” — Marcus Crane (Halter, ex-Lightspeed)

I don’t know who needs to hear this, but open-source ≠ free and Backstage is Exhibit A. Even if you never pay Spotify a cent, you’ll still spend real money (and calendar time) in four places:

• Engineering hours — 3-5 full-time engineers seems to be the ideal size for a Backstage support team (those with less often struggle with workload)
  
• Front-end expertise — plugins are React/TypeScript; several Platform teams had to upskill or hire FE help
  
• Infrastructure & SRE — you run the thing: CI/CD, auth, Postgres, monitoring, backups, staging environments, etc
  
• Commercial add-ons — Some plugins are paid, like Spotify’s own Soundcheck, and they can cost as much as a standalone vendor

The SRE costs should not be underestimated. As one user put it:

“Once people started relying on Backstage, it really needed to be treated like a production service. It had to be up and reliable all the time, otherwise we literally couldn’t ship or troubleshoot anything.” — Julio Zynger (Zenjob, ex-SoundCloud)

Back-of-the-napkin numbers:

• DIY Backstage with 3 engineers in a mid-size org: US $380-650k per year (incl. modest infra)
  
• Fully managed SaaS IDP for 200 engineers @ $35/dev/mo: $84K per year
  
• Hybrid DIY core + premium plugins and fewer (1-2) devs: $150-250k per year

Your mileage will vary, but the lesson is clear: building an IDP is a major investment that needs to be planned with ROI in mind.

Common Pitfalls with Backstage

These are some of the common challenges I heard from the 20+ Backstage teams I’ve spoken to.

1. Under-estimating head-count (and FE skills)

“You need someone who can actually write TypeScript if you want to keep building plugins. That’s hard when your org is all Go devs.” — Lucas Weatherhog (Giant Swarm)

Most teams that thrive on Backstage dedicate 3-5 engineers, including at least one comfortable in React/TypeScript. Under-staff it, and you may struggle to make meaningful progress. A single engineer supporting 130 users on Backstage said this:

“Almost all my time goes into keeping the catalog data accurate. There’s no bandwidth left to build plugins.” — Alexandr Puzeyev (Tele2 Kazakhstan)

2. Docs for everyone? Not quite

“TechDocs works great for the engineers, but when we asked the designers and PMs to learn GitHub and write Markdown, it just wasn’t going to happen. They stuck with Confluence.” — Rory Scott (Duo Security, ex-Fanatics)

Backstage shines for code-adjacent docs. Non-engineering teams usually keep their own tools, and that’s okay.

“Backstage feels like it’s built for developers first. The UI, the YAML, the whole mindset. Tools like Cortex look great on a leadership dashboard, but they don’t speak to engineers the way Backstage does.” — Adam Tester (Deel)

3. Chasing 100% adoption

I previously wrote about this on platformengineeringisdead.com (as part of a PlatformCon stunt). Successful Backstage initiatives aim for 80% of use-case coverage. Pushing for the last 20% often burns more hours than it’s worth, especially with Scaffolder, where retro-templating legacy services quickly snowballs the backlog.

If your goal is universal standards, consider tools that enforce them outside the template path (Earthly Lunar). Meanwhile, lean on automation to lighten the catalog load:

“We generate the catalog-info.yml files automatically from our internal service registry. Developers only jump in to tweak things if the script gets something wrong.” — Andy Vaughn (AppFolio)

4. Missing exec sponsorship

“If you’re a big, tech-heavy organization and you really have leadership support to invest in developer experience, then you should adopt something like Backstage. But if leadership support isn’t there, don’t even go down that road.” — Yaser Toutah (Talabat, ex-Expedia Group)

Getting enough capacity to support Backstage—and persuading other teams to adopt it—requires leadership backing. Teams that treated Backstage as an after-hours side project and waited for organic uptake usually stalled out within months.

How to Succeed with Backstage (and Prove ROI)

Building an IDP takes real effort, but many teams see a clear pay-off once they can measure the benefits.

Backstage demands proof. If you can’t show hard numbers, your portal will be the first line-item to vanish in the next budget review. Here are several example metrics to turn your “nice portal” into a “business win”.

“We proved we could deliver a microservice into an environment in about 60 seconds. It used to take four to six weeks.” — Matt Law (The Warehouse Group)

A simple playbook:

1. Anchor on a pain with a price-tag — Three to five engineers for 6–12 months costs real money. Show what it will save or unlock.
   
2. Run a laser-focused pilot — If docs sprawl is the sore spot, tackle only TechDocs first. Partner with one or two friendly teams.
   
3. Publish the numbers — Compare pilot metrics to baseline. Turn the wins into a one-pager for execs and an internal demo for peers.
   
4. Scale with advocacy — Use leadership sponsorship, early-adopter testimonials, and brown-bag demos to bring in the next wave of teams.
   
5. Rinse & repeat for a new use-case — When the catalog is humming, circle back to step 1 for Scaffolder, plugins, and other use cases.

Keep the loop small, measurable, and relentlessly tied to business value. Backstage will sell itself once the numbers do.

So… Is Backstage Really Worth It?

When it lands, the pay-off is real: teams report slashing days of boilerplate work, onboarding faster, and spending less time hunting for “who owns this?” But for every smooth rollout there’s a cautionary tale where DIY effort ballooned faster than the ROI could keep up.

Want a deeper dive into the history and current adoption trends? Check out “Backstage Is at The Peak of Its Hype”.

If you do commit, remember: running Backstage is like launching an internal startup. You’ll need a clear problem statement, executive investors, a roadmap, and a team that treats fellow engineers as customers. (P.S. If the startup life is for you, we’re hiring)

Ready to raise the bar in engineering excellence?

Earthly Lunar is the SDLC monitoring platform built for the messy reality of engineering at scale. It’s like production monitoring, but for everything that happens before production — bringing real-time visibility into your entire development lifecycle: from commit to deploy, without changing dev infrastructure.

Policy Engine for your SDLC
Lunar monitors your code and CI systems to collect SDLC metadata (config files, test results, IaC usage, dependency declarations, security scans, and more). It continuously evaluates this data against your organization’s engineering standards, then enforces those policies by providing feedback to developers directly in their PRs.

It even integrates with your existing Backstage or other software catalogs.

👉 See it in action