TL;DR - A developer portal is the index of your paved roads, and almost nobody should build the index before they have the book. Standing up Backstage as your first platform move gives you an empty catalogue, a maintenance burden, and a demo that impresses leadership while helping zero developers. You earn a portal once discovery is a real problem - roughly the ~30-services mark the pillar names, several paved roads worth cataloguing, and ownership data someone actually maintains. Before that, a boring markdown catalogue does the same job for a thousandth of the cost. This is the post-script to building your first golden path: what comes after the road, and why it isn’t the portal.
There’s a meeting that happens in almost every engineering org that decides to “get serious about platform engineering”. Someone has seen the Spotify demo, or read a thread, and says the words: “we should set up Backstage.” Heads nod. It feels like the responsible, grown-up move. A portal is what real platforms have, and now you’ll have one too.
I want to talk you out of that meeting, or at least out of its timing. Not because portals are bad - a good one is genuinely excellent - but because building it first is the single most reliable way I know to spend six months and have nothing developers use to show for it. I said this in passing when I wrote about your first golden path: the portal is the index of your paved roads, and you don’t write the index before the book. This post is the long version of that sentence.
What a developer portal actually is
Strip away the framework and a developer portal is three things glued together:
- A service catalogue. The answer to “what services exist, who owns them, and how do I reach them.” This is the part with real, durable value, and it’s also the part that’s worthless if it isn’t accurate.
- Software templates. Scaffolding for “create a new X” - which, if you’ve done the work, are just your golden paths given a UI. The template is the paved road; the portal is the front door to it.
- Aggregated context. Docs, dashboards, scorecards, the on-call rotation, the runbook - the stuff that’s scattered across a dozen tools, pulled into one place keyed by service.
Notice that the value in all three is the content, not the framework. A catalogue is valuable because it’s accurate, not because it’s Backstage. Templates are valuable because they encode real opinions, not because they render in a plugin. The pillar makes this point plainly: the value is the service catalogue and the paved-road templates, not the framework itself. Hold onto that, because it’s the whole argument.
Why building it first is the trap
When the portal is your first move, every one of those three things is empty or fake, and the failure modes line up like dominoes.
- An empty catalogue is worse than no catalogue. A catalogue with three services in it, two of them wrong, teaches developers exactly one lesson: don’t trust the catalogue. And a catalogue nobody trusts is a catalogue nobody updates, which is a catalogue that gets more wrong every week. The thing degrades on its own.
- Templates with no paths behind them are just folders. A “create new service” button that scaffolds a repo you haven’t actually paved - no real pipeline, no wired-in observability, no opinionated defaults - is a worse version of copy-pasting from an old repo, because now it’s copy-pasting with a UI and a maintainer. You can’t surface golden paths you haven’t built.
- The maintenance tax starts on day one and never stops. Backstage is not a thing you install. It’s a Node application you now operate: catalogue ingestion, auth integration, plugin upgrades, the catalogue-info files every team is supposed to keep current and won’t. You’ve taken on a product to maintain before you’ve shipped a product anyone wanted.
- It produces the most dangerous artifact in platform engineering: the impressive demo. A portal demos beautifully. Leadership sees a single pane of glass and concludes the platform is real. Meanwhile the developers it was for still file the same tickets, because nothing in the pane of glass removed a single decision from their day. The demo buys you political capital and spends your actual runway, and the gap between “looks done” and “is used” is where platform teams quietly die.
This is the complexity tax in its purest form: you’ve bought a heavyweight abstraction to manage a problem - too many services to keep track of - that you don’t have yet. The portal isn’t solving a discovery problem. It’s a discovery problem you’ve added to your plate, dressed as a solution.
When you’ve actually earned a portal
The honest signal isn’t a service count, it’s a feeling, and the feeling is “I can no longer hold the system in my head.” When a new engineer has to Slack three people to find out which team owns the payments service, when you genuinely don’t know how many services are in production, when the same incident gets routed to the wrong team twice in a quarter - that’s discovery becoming a real, recurring, expensive problem. That’s the problem a portal solves.
The pillar puts a number on it - Backstage is worth it once you cross ~30 services - and a number is useful as a smell test, but treat it as shorthand for the underlying conditions, all of which have to be true together:
- Discovery genuinely hurts. Not “would be nice to have a list.” Actively costs you time and mis-routes work, today, repeatedly.
- You have paths worth cataloguing. Three or four real golden paths in production. The portal indexes them; it does not replace building them.
- Ownership data exists and someone keeps it true. A catalogue is only as good as its freshness. If no one owns “is this still accurate?”, the portal rots into a liability the day after launch.
- The org is big enough that out-of-band coordination has broken down. Below a couple of dozen engineers, a shared README and a shared opinion still fit in everyone’s head. The portal is a coordination tool for when coordination stops scaling, the same threshold that justifies most platform investment.
If you can’t check all four, you haven’t earned the portal yet. You’ve found another way to feel productive without being useful.
The cheaper version you almost certainly want first
Here’s the part the Backstage demo doesn’t mention: for most of the journey, you can get 80% of a portal’s value from something you can build in an afternoon and operate for free.
A service catalogue is, at its core, a list. A markdown file in a repo, a table in your wiki, or a tiny generated page that reads a service.yaml from each repo and renders it - any of these answers “what exists and who owns it” without you operating a Node application. It’s ugly, it’s not a single pane of glass, and it works. When teams keep it current because it’s two lines in a file they already touch, you have something more valuable than a beautiful catalogue nobody trusts: an accurate one.
This is the boring stack applied to the platform’s own tooling. Don’t buy the heavyweight abstraction until the lightweight one visibly breaks. The day your markdown catalogue is genuinely too painful - too many entries, too much manual upkeep, real demand for plugins and scorecards and live dashboards - is the day a real portal stops being premature and starts being obvious. Let the cheap version fail before you build the expensive one. That failure is the only reliable proof you needed the upgrade.
When a portal is the wrong answer entirely
Some teams will never need one, and pretending otherwise is just aspirational architecture.
- Small, stable orgs. Three teams and fifteen services that everyone already knows? A portal is a solution looking for the scale that justifies it. You’d spend more time maintaining catalogue metadata than you’d ever save looking things up.
- When the real problem is the paths, not the index. If your developers’ pain is “shipping a new service is a week of yak-shaving,” a portal does nothing for them. Go build the paved road instead. The portal is downstream of paths that don’t exist yet.
- When you can’t staff the upkeep. A portal nobody maintains is strictly worse than no portal, because it actively misleads. If you can’t name the person who owns catalogue accuracy, don’t start.
This is the same judgment I apply to Kubernetes: the abstraction has to be cheaper than the problem it hides. A portal hides the cost of not knowing what you run. If that cost is small - because the org is small, or because the real bottleneck is elsewhere - the portal is pure overhead with a nice UI. Fluency in platform work is knowing which side of that line you’re on before you helm install anything.
The bottom line
A developer portal is a genuinely great thing to have and a genuinely terrible thing to start with. It’s the index of your paved roads, and an index of an empty shelf is just a maintenance burden with a login page. The trap isn’t Backstage. The trap is sequence: reaching for the artifact that signals a mature platform before doing the unglamorous work that is one.
So build the roads first. Pave the most-repeated, most-painful path, get a team to use it, pave the next one. Keep a boring markdown list of what you’ve got and who owns it. And when that list finally buckles under its own weight - when discovery genuinely hurts, you’ve got real paths to catalogue, and someone will keep the data true - then, and only then, go build the portal. By that point you won’t be hoping it makes the platform real. You’ll be giving an index to a book that already exists.
If you’ve got a platform that’s all portal and no paved road, or you’re about to start with Backstage and something feels backwards, let’s talk.