Taming a frontend codebase that grew too fast
Your product won, your codebase lost. A practical playbook for bringing a fast-grown frontend back under control — without stopping the roadmap and without the dreaded rewrite.
There is a specific kind of codebase that only successful products have. It shipped fast, it won customers, and every sprint someone bolted a new feature onto whatever was nearest. Three years later the product is thriving — and the frontend is a haunted house. Every developer has a wing they refuse to enter.
If that sounds familiar: congratulations, and my condolences. Here is the playbook I use when a team calls me in at that exact moment.
First, name the actual problem
"Tech debt" is a useless diagnosis — it points everywhere and therefore nowhere. In practice, fast-grown frontends almost always hurt in a handful of specific places:
- State lives everywhere. Server cache, global store, component state and the URL all disagree about what is true.
- Components do too much. The 900-line component that fetches, transforms, renders and navigates — and is imported in eleven places.
- Patterns diverge by author. Three ways to call the API, four ways to handle errors, two competing folder structures — depending on who wrote it and in which year.
- Nobody trusts a change. No tests where it matters, so every release is a small act of courage.
Spend a week measuring instead of refactoring: where do bugs cluster? Which files change in every single feature? That map — change frequency × defect density — tells you where the leverage is. It is usually 4–6 files, not four hundred.
The rules of engagement
No rewrite. A rewrite trades problems you know for problems you don't, and freezes the roadmap while you rediscover them. The business that funded your growth will not fund a year of "nothing new, we promise it's better inside".
The boy-scout rule is not a strategy. "Leave it better than you found it" produces random acts of tidiness. Improvement has to follow the leverage map, not the developer's mood.
Every step ships. If a refactor can't reach production independently, it's too big. Cut it down until it can.
The playbook
1. Freeze the bleeding
Before improving anything, stop making it worse. Agree on one blessed pattern for the big four — data fetching, state, error handling, folder structure — and enforce it on new code only, in review and with lint rules. The old code stays untouched for now. This costs almost nothing and immediately splits the codebase into "legacy" and "the way out".
2. Build the paved road
Take the most common thing your team builds — a list-plus-detail screen, a form flow — and create the reference implementation: typed API layer, error boundaries, loading states, tests. Not a wiki page. Working code in the repo that people copy. A pattern that isn't easier to follow than to ignore will be ignored.
3. Strangle by traffic, not by tidiness
Now walk the leverage map. The high-churn, high-defect modules get rebuilt onto the paved road first — one at a time, each shipped to production behind the same URL. Low-churn ugly code stays ugly. It has earned the right: it works and nobody touches it. Aesthetic refactoring of stable code is how modernisation budgets die.
4. Make the trend visible
Pick two or three numbers the whole team can see move: type coverage, bundle size, defects per release, time-to-merge. Post them monthly. Teams that watch a trendline defend it; teams that don't slide back within a quarter.
What this looks like in real life
On a large e-commerce storefront I led, we did exactly this: standards enforced in review from week one, strict TypeScript as the paved road, and the core catalogue components — the highest-churn area of the codebase — rebuilt incrementally while the release train kept running weekly. No feature freeze, no big-bang branch, and within two quarters the team was measurably faster and calmer. The second part matters more than it sounds: a team that stops fearing its own codebase makes better decisions everywhere else too.
The honest timeline
For a mid-size product frontend, expect the turnaround to be a quarters game, not a weeks game — but with the curve bending early: the bleeding stops in week one, the paved road exists within a month, and the first high-leverage module ships soon after. If someone promises you a transformed codebase in three weeks, they are describing a demo.
I work as a software architect with a front-end focus — modernising products that grew faster than their code, without stopping them. If your frontend has become the part of the roadmap everyone routes around, let's talk: a 30-minute intro call is free and usually clarifying.