Inheriting a live codebase

We took over the Armygadget project in April. The codebase wasn't ours — it was already running, already serving two paying clients, and already a little behind on the dependency front.

So, naturally, the first thing we did was run npm outdated.

The list was long. Long enough that we did the thing every engineer does at least once: select all, update all, run the build, hope for the best. The build, of course, did not hope for the best. It hoped for catastrophic version conflicts and got exactly that. Nothing left our machines. But the message was clear: blind updates weren't an option.

OK, smaller scope. Just React. Just bring React up to date, deal with everything else later.

A few hours in, we had a half-migrated app, a stack of GitHub issues open in tabs, and three different AI models all confidently giving us three different wrong answers. The blocker turned out to be one library we'd forgotten was in the tree at all: react-helmet-async. Its peer-dep range had been frozen on npm since 2024 — React 16, 17, 18. No 19.

Every model we asked said the same thing: rip it out. Switch to react-helmet. Write your own Head component. Migrate the whole app to Next.js. None of them mentioned that react-helmet-async@3.0.0 had been published a few weeks earlier with exactly the peer-range widening we needed. One-line bump, problem solved. Their training cutoffs were all a few months too early to know it existed — but we wouldn't figure that out until much later.

At the time we just looked at the failing build, the four conflicting AI suggestions, and did the only sensible thing left: we stopped.

The plan changed. Instead of cleaning the house before moving in, we'd move in and clean as we went. Armygadget needed a website — pages, product cards, category views, the whole storefront — so we'd build that on top of the codebase as it was, and bump dependencies in small, boring increments along the way.

This turned out to be a much better plan. The Armygadget team turned around feedback inside a day, which is the only reason the page-by-page rhythm worked. Build a page, ship to staging, get notes back the same day, fix, repeat. Small details came in flights — a tweak to a product card, a missing field on a category page, a copy change. The thing started to look like a website. Then it started to feel like one.

A few weeks in, the Raxel and Armygadget teams looked at v1 together and called it: time to go live.

The lesson here is one we keep relearning: when you inherit a live codebase, the temptation is to fix it first. Don't. You'll burn weeks proving you can keep something running that was already running. Build the thing the client actually wants, and let the cleanup ride alongside.

We'd come back to those dependencies eventually. But that's a story for another post.