Alexander Antoniades, Frontend Chapter Lead
Alexander Antoniades is the Frontend Chapter Lead at TalentLMS. He spends his days obsessing over web performance and front-end architecture — the kind of work where shaving off 50 milliseconds feels …

You just finished a feature. Nothing dramatic. A small screen, a form, a couple of helpers. Now you’re sitting there holding the leftovers. A custom hook. A little utility function. A type or two. A stylesheet. And you have to decide where each one goes.

In the old codebase, that was a real decision. The hook could go in the global hooks/ folder. The helper could go in utils/. The type in types/. The style next to something, somewhere. Every file you wrote came with a small fork in the road, and everyone picked a slightly different branch.

So the code for one feature ended up smeared across five different top-level folders. To understand the catalog page you opened components/, then hooks/, then utils/, then types/, and none of those folders was called catalog. The feature existed. It just didn’t live anywhere. It was scattered.

Organizing by type sounds tidy

The instinct behind the old layout is a good one. Put all the components together. All the hooks together. All the utilities together. It looks like a library. It looks organized.

It reads fine right up until you have more than a handful of features. Then the shared folders turn into drawers you’re afraid to open. utils/ has two hundred functions in it and you have no idea which screens use which. hooks/ is the same. You want to change one helper and you can’t tell what you’ll break, because anything is allowed to import anything, and over a couple of years, everything did.

That’s the real problem with grouping by type. It puts unrelated things next to each other and invites them to get tangled. A helper written for one screen gets quietly reused by three more. You change it for the first screen, and two screens you’d never heard of break in a way nobody catches until a customer does.

Shared-by-default is how a codebase slowly ties itself in knots.

One folder per feature

So a couple of years ago I wrote it down as a decision. Stop organizing by type. Organize by feature.

Every feature gets one folder. Everything that feature needs lives inside it. Its components, its hooks, its API calls, its types, its helpers, its constants, its styles, its tests. All of it, in one place, named after the thing it actually is.

A feature folder looks like this:

CustomHomePage/
├── __tests__/                 // tests for this feature
├── components/                // components used only here
├── hooks/                     // hooks used only here
├── layouts/                   // layouts specific to this feature
├── api.ts                     // this feature's API calls
├── index.ts                   // the feature's main export
├── types.ts                   // this feature's types
├── utils.ts                   // this feature's helpers
├── constants.ts               // this feature's constants
└── customHomePage.styles.ts   // styles for the main component

Now the question that started this post has a boring answer. Where does the hook go? In the feature folder. Where does the helper go? In the feature folder. The type, the style, the test? Feature folder. You stop standing at a fork, because there isn’t one anymore. The default is always “next to the thing that uses it.”

And finding code gets just as boring. To understand the catalog, you open views/Catalog and it’s all there. You don’t go on a tour of six directories. The feature lives in one, and it’s named after itself.

Shared has to earn it

The root-level folders didn’t go away. We still have api/, hooks/, utils/, stores/, and the rest. They just changed jobs. They are now only for things that are genuinely used across more than one feature.

The rule we follow is small. Code starts local, inside its feature. It only moves up to a shared folder when a second feature actually needs it. Not when you have a hunch it might be reused someday. When it’s really needed, by real code, in a second place. Sharing too early is how the old junk drawers filled up in the first place, so we made “keep it local” the lazy, default choice and “make it shared” the deliberate one.

There’s a middle ground too, for the awkward case. Sometimes a bit of code is shared by a few parts of one big feature, but nothing outside it. That doesn’t belong in the global folders, and it doesn’t belong buried in one sub-part. So a feature can have its own shared/ folder for exactly that. Our CourseStore and Subscription features both have one. It keeps the “shared” honest: local until a real neighbor needs it, and no higher up the tree than it has to be.

One more small rule that trips people up: a feature’s own store lives with the feature, not in the root stores/. The root is for state the whole app leans on. Everything else stays home.

A convention nobody enforces is a suggestion

Here’s the part I got wrong the first time.

You can write all of this down. You can put it in a document, give it a nice diagram, and present it to the team. And it will hold for about a month. Then someone in a hurry imports a helper from another feature because it was right there and it worked, and the reviewer is busy that day, and now there’s one thread connecting two features that were supposed to be strangers. Do that fifty times and you’re back where you started, except now there’s a document claiming you’re not.

A rule that only lives in a document is a suggestion. To actually keep the boundaries, they have to be checked by something that doesn’t get tired or busy.

So we made the structure defend itself. A tool called dependency-cruiser runs on every pull request, and it knows the boundaries as real rules:

components   cannot import from   views
hooks        cannot import from   views
utils        cannot import from   views
views/A      cannot import from   views/B

Shared code is not allowed to reach down into a feature. One feature is not allowed to reach sideways into another. There’s a rule against circular imports for good measure. The moment someone crosses a line, the build stops and says no, right there in the pull request, before a human has to notice. The layout isn’t a promise we keep by being careful. It’s a fact the CI enforces whether we’re careful or not.

What gets easier once it sticks

None of this is the point on its own. The point is what it makes ordinary.

Changing code stops being a gamble. When a helper lives inside the feature that uses it, you already know who depends on it: this feature, and nobody else. You can rewrite it, rename it, or delete it outright without first tracing every import across the tree. The blast radius of a change is the folder you’re standing in, and you can see the whole folder at once.

And when something does break, you know where to look. A bug in the catalog lives in the catalog folder, because that’s where the catalog’s code lives. You’re not bouncing between six directories trying to work out which shared helper got handed the wrong value three features away. The stack trace points at a folder, and the folder holds the whole story.

Deleting code gets easy, which almost never happens anywhere. When a feature is retired, you delete its folder and you’re finished. There are no orphaned helpers left behind in utils/, no lonely hook that three screens still import for one line nobody understands. The feature arrived as one unit, and it leaves as one.

And two people can build at once without elbowing each other. Two features are two folders, so two engineers working on two things rarely touch the same files. The merge conflicts that used to bloom in the shared drawers, everyone editing the same utils.ts from opposite directions, mostly just stop.

The honest tradeoffs

This is not free, and pretending otherwise would be a lie.

You get some duplication. A tiny helper sometimes gets written twice in two features instead of shared once. That looks wasteful, and now and then it is. But a copied ten-line function is a much smaller problem than a shared one that secretly welds two features together. Duplication you can see. Coupling you can’t.

You also get more folders and more files. Someone new to the codebase, looking at a feature with its own little components and hooks and utils, might feel it’s a lot of ceremony for one screen. And there’s a short adjustment period where people have to unlearn the reflex to drop everything in a global folder.

I’ll take all of that. Those downsides are visible and shallow. The thing it prevents, a codebase quietly tying itself into a knot over three years, is the one that actually hurts.

The payoff is that it’s boring

The best thing I can say about this structure is that nothing interesting happens anymore.

A new engineer joins and, within a day, can guess where any piece of code lives, because there’s one rule and it’s the obvious one. A new AI coding assistant reads the repo and puts new files in the right place, because the right place is predictable. Code review stops including the phrase “actually, can you move this.” Where does this file go? It has exactly one answer, every time, and nobody has to think about it.

Put it next to the thing that uses it. Move it up only when something else truly needs it. Let the build enforce the rest.

That’s the whole idea. It’s not clever. It was never supposed to be.

Alexander Antoniades, Frontend Chapter Lead
Alexander Antoniades is the Frontend Chapter Lead at TalentLMS. He spends his days obsessing over web performance and front-end architecture — the kind of work where shaving off 50 milliseconds feels …

The AI assistant handed me a component. Clean, typed, tests included. It also used an interface instead of a type, pulled a helper in through a relative ../../../utils path, and hardcoded a user-facing string in English. Three of our conventions, broken in one file, and not a trace of doubt about any of it.

It wasn’t the tool’s fault. It had never read our rules. We had rules, plenty of them, but they lived in a wiki, and the tool had no way to reach them.

You can’t expect a machine to follow conventions you keep somewhere it never looks.

Three tools, three files

So we started writing the rules down where the AI would actually see them.

Claude Code reads a CLAUDE.md at the root of the repo. So we wrote one. It worked. The generated code started respecting our patterns because, for the first time, the patterns were sitting in the assistant’s context instead of in a wiki.

Then people started using Cursor. Cursor doesn’t read CLAUDE.md. It reads its own thing under .cursor/. So we wrote those rules too. Then Copilot arrived, and it reads .github/copilot-instructions.md. So we wrote a third copy.

Three files. The same conventions. Written out three separate times.

You already know how this ends. Someone tightens the testing convention in CLAUDE.md. The Cursor rules still describe the old way. The Copilot file has quietly become a fossil. Now the three tools disagree with each other, and all three disagree with the actual code. We had taken one documentation problem and turned it into three.

One file, symlinked

The fix was almost embarrassing.

One file, and only one. We didn’t even have to name it ourselves. There’s an open format for exactly this called AGENTS.md, a plain-Markdown file that coding agents look for the way a person looks for a README. The big AI coding tools already agreed on it, so it wasn’t something we had to invent. Using their shared standard beats making up our own.

So AGENTS.md became the one real file. For the tools that still expect their own filename, we pointed those names at it:

CLAUDE.md                        -> AGENTS.md
.github/copilot-instructions.md  -> ../AGENTS.md

Symlinks. Claude Code opens CLAUDE.md and gets AGENTS.md. Copilot opens its file and gets AGENTS.md. One file to edit. No sync script, no CI job copying paragraphs from one place to another, no drift, because there is only one file and everything else is a pointer to it. The filesystem does the work for free.

The Cursor wrinkle

Cursor did not fall in line quite so neatly.

It doesn’t load a single instructions file the way the others do. It reads small rule files under .cursor/rules/, each with a bit of frontmatter that can mark it as always applied. Fine. We can write those.

Here’s the part that caught us out. Cursor injects the text of a rule into the model’s context. It does not follow a link inside that rule and go read the file it points to. So a rule that helpfully said “for testing conventions, see .claude/skills/unit-test/SKILL.md” was worse than writing nothing. Cursor pasted that one sentence and stopped. The conventions, one link away, never loaded. The agent went off and did its own thing, and we assumed it had the rules, because we had, technically, written a rule.

A link is not a load. That sounds obvious written down. It is not obvious at all when you’re staring at a rule file that clearly mentions the thing the agent is clearly ignoring.

So the .mdc files stopped trying to be the rules. They became triggers. Each one is short. A handful of the load-bearing bullets, and then an instruction aimed at the agent itself: before you write anything for this kind of task, go read this skill file. Not a summary pretending to be the whole thing. An order to go get the whole thing.

Here’s what one of them actually looks like, the rule for writing tests:

---
description: Vitest + RTL test generation (integration-first; always applied)
alwaysApply: true
---

# Tests (Vitest + RTL)

- Co-locate `__tests__/{name}.test.jsx` (components/hooks) or `.test.js` (pure functions); camelCase filenames.
- Render via `@test-utils/render`; Vitest globals without imports; no direct `@testing-library/react`.
- Mock with `vi.mock()`; test behavior and a11y, not implementation details.

**Full detail:** [`.claude/skills/unit-test/SKILL.md`](../../.claude/skills/unit-test/SKILL.md) — also load `references/*` when generating tests.

The bullets are a nudge for the common case. The last line is the real instruction: the rest lives in the skill, go open it. The rule is deliberately too small to be the whole story, so it can’t quietly rot into a stale half-copy of one.

The file that ate itself

While all this was happening, AGENTS.md developed a problem of its own. It was succeeding.

Every time we caught the AI getting a convention wrong, we added a section to fix it. Naming. Then styling. Then the API layer. Then testing, with examples. Then a list of anti-patterns. Then examples of the anti-patterns, so nobody could claim ambiguity.

It grew into something enormous. Hundreds of lines. And something predictable happens to a document that long. The agents started skimming it, the exact way you skim a terms-of-service page you have no intention of reading. The genuinely important rule about facades was sitting somewhere around paragraph forty, and by paragraph forty nobody was reading closely anymore. Not the humans, and not the agents we’d written the whole thing for. It slowed every session down, too. Each one began by loading a small book before it got to do any actual work.

We had recreated the original problem in a new location. A pile of rules nobody reads. Same pile, better address.

So we turned it inside out. AGENTS.md stopped being the rules and became the index to the rules. It’s about a hundred lines now, and most of that is a routing table. A topic on the left, the one file that owns it on the right.

A slice of it reads like this:

| Topic                        | Canonical file                                         |
| ---------------------------- | ------------------------------------------------------ |
| React / TS / API / styling   | docs/guidelines-conventions/engineering-conventions.md |
| Tests (Vitest + RTL)         | .claude/skills/unit-test/SKILL.md                      |
| Naming                       | docs/guidelines-conventions/naming-conventions.md      |
| Folder structure             | docs/ADR/00001-folder-structure.md                     |
| PR / commits                 | docs/processes/CREATE_PULL_REQUEST.md                  |

Nothing in that file explains how to name a test or lay out a folder. It just knows which door to open. The discipline we hold ourselves to is a single line at the top: one topic, one file. Every convention has exactly one canonical home, and AGENTS.md only ever needs to know the address.

Now an agent reads a short index, finds the row that matches its task, and loads that one file. Not the book. The one chapter it needs for the thing it’s about to do.

The wiki was the real problem

There was still the matter of the wiki. All those original pages, the ones that kicked this off. For a while we treated them as the source and copied fragments into the repo, which, if you’ve been paying attention, is the drift problem again. Just slower and more polite about it.

Documentation in a wiki rots for a plain reason. It sits nowhere near the code, and nobody reviews it. You change how testing works inside a pull request, where two people look at the diff and argue about it. The wiki page describing how testing works just sits there and ages, until a new hire follows it to the letter and ends up confused in a channel asking why nothing matches.

So the pages are moving into the repo. Each convention becomes a file that lives next to the code it describes. Changing one means opening a pull request, which means someone reviews it, the same as any other change we make. The old Confluence pages now carry a banner across the top telling you they’re being migrated and to make your edits in the repo, not there.

And the AI reads all of it at no extra effort, because it’s finally sitting in the place the AI was already looking.

What we took from it

• One canonical file, symlinked to whatever names your tools insist on. Let the filesystem prevent drift instead of trusting a script and a good mood.
• Learn how each tool actually loads context before you write for it. Cursor pastes a rule and stops. A link is not a load. Write triggers that send the agent to read the source, not summaries that quietly pretend to be it.
• A rules file long enough to be complete is long enough to be ignored. Index, don’t inline. One topic, one file, one home.
• Put the docs where the work is. Conventions in a wiki are conventions on their way out. In the repo they get versioned, reviewed, and actually read.

The thing that caught me off guard was who ended up benefiting. We did all of this for the robots. But a convention that’s short, findable, kept in the repo, and reviewed in a pull request turns out to be a better convention for the people too. The new engineer and the new AI assistant now start from the same page, literally.

The AI never needed special treatment. It needed what everyone always needed and rarely got. The rules, written down once, kept current, and left somewhere you’d actually think to look.

Alexander Antoniades, Frontend Chapter Lead
Alexander Antoniades is the Frontend Chapter Lead at TalentLMS. He spends his days obsessing over web performance and front-end architecture — the kind of work where shaving off 50 milliseconds feels …

It’s a Monday. You open Sentry before you open anything else, because that’s the job now. There’s a new issue at the top. A white screen, a component that threw, a stack trace that’s been minified into hieroglyphics. The error message is undefined is not an object. Helpful.

You stare at it. The real question isn’t what broke. React already told you what broke. The question is whose it is.

Usually you can answer it. Read the stack trace, recognize a component, match it to a team. Most of the time that’s a minute of work. Occasionally you guess wrong, ask in a channel, and someone points you the right way.

None of that is hard. It’s just manual. A small tax you pay every time an error comes in, on a question the app already had the answer to and simply never wrote down.

The boundary that caught everything and told you nothing

We weren’t reckless. We had error boundaries. We’d done the React thing. Wrap the app, catch the throw, show a polite fallback instead of a blank white void.

The problem is what “the React thing” looked like in practice. One boundary, sitting at the very top of the tree, catching everything. A single net under the entire trapeze act.

It did its job. The app didn’t show users a stack trace. It showed them a tasteful “something went wrong” screen instead. That part worked.

But from a triage perspective, every error in the building arrived wearing the same uniform. A crash in the course player and a crash in the billing settings and a crash in a dashboard widget all showed up in Sentry looking identical. Same boundary. Same fallback. Same shrug.

We had observability into that something went wrong. We had nothing into who should care.

In a company with more than one team, errors aren’t homeless. Every screen belongs to someone. The course player is Courses. Billing is Business. Integrations is, well, Integrations. The information existed. It lived in people’s heads and in the org chart and in the routing table. It just never made it into the error report.

So we kept answering, by hand, a question the code could have answered for us.

The fix is not “catch more errors”

When the team finally sat down to fix this, the first instinct was wrong. Mine included. We assumed it was a coverage problem. More boundaries. Smaller boundaries. Catch errors closer to where they happen.

That’s part of it. But it’s not the part that mattered.

The part that mattered was attribution. An error report is only as useful as the question it answers, and the question we cared about was ownership. We didn’t need to catch errors better. We needed every error to walk into Sentry already knowing its team.

Sentry has a primitive for exactly this. Tags. You can attach arbitrary key-value pairs to an event, then filter and alert on them later. team:courses. team:business. Suddenly the dashboard isn’t a pile of anonymous stack traces. It’s filterable by the people who can actually fix things.

The only question left was where to attach the tag. And that question turned out to be more interesting than it sounds.

Tag the route, not the component

The obvious place to put a team tag is inside the component. The course player knows it’s the course player. Just have it announce itself.

Good thing we didn’t.

Because component ownership is a lie that drifts. Teams get renamed. Responsibilities shift. A view that belonged to Courses in January can become Content’s responsibility by June as team boundaries and ownership evolve over time. If the team identity is sprinkled across a hundred components, updating it means a hundred edits and a prayer that you found them all.

The routing table doesn’t drift like that. It’s the one place in the app where “this screen exists, and here’s how you reach it” is written down on purpose. If you want a single source of truth for who owns what screen, the route definitions are already it. You’re just not using them that way yet.

So that’s where the tag goes. We wrote a small higher-order component that wraps a view in a Sentry error boundary and stamps the team onto the error before it’s ever sent:

export const withSentryBoundary = <P extends object>(
  Component: React.ComponentType<P>,
  { fallback = <FallbackErrorScreen />, tags = {} }: WithSentryBoundaryOptions,
): React.FC<P> => {
  const WrappedComponent: React.FC<P> = (props) => (
    <ErrorBoundary
      fallback={fallback}
      beforeCapture={(scope: Scope): void => {
        Object.entries(tags).forEach(([key, value]) => {
          scope.setTag(key, value);
        });
      }}
    >
      <Component {...props} />
    </ErrorBoundary>
  );

  WrappedComponent.displayName = `withSentryBoundary(${Component.name})`;
  return WrappedComponent;
};

The important word there is beforeCapture. It’s a hook Sentry gives you that runs on the boundary’s own scope before the error event leaves the building. So by the time the crash is reported, the team tag is already on it. Not added later. Not inferred. Already there, attached at the moment of capture.

And then in the routing table, each view declares its owner exactly once, right where it’s wired up:

withSentryBoundary(Catalog,   { tags: { team: Teams.COURSES } })
withSentryBoundary(Dashboard, { tags: { team: Teams.BUSINESS } })
withSentryBoundary(Automations, { tags: { team: Teams.INTEGRATIONS } })

The teams themselves live in one tiny file, so nobody invents a typo’d team name at two in the morning:

const Teams = {
  BUSINESS: "business",
  CORE: "core",
  COURSES: "courses",
  CONTENT: "content",
  INTEGRATIONS: "integrations",
} as const;

That’s the whole trick. The error doesn’t know what team it belongs to. The route does. And the route is the thing least likely to lie to you.

Three nets, not one

Once the tagging worked, the coverage question came back. This time we knew why we were answering it. Different crashes deserve different blast radii.

So we ended up with three layers, and they’re layered on purpose.

At the very top, in the app’s entry point, there’s still one boundary catching everything. The last line of defense. If something escapes every other net, this one stops the user from staring at a blank document, and shows a full-page fallback instead.

<ErrorBoundary fallback={<FallbackErrorScreen isFullPage />}>
  {/* the entire application */}
</ErrorBoundary>

This boundary should almost never fire. When it does, it means something got past everything else, and that’s worth knowing on its own.

The middle layer is the route level. The withSentryBoundary wrappers from earlier, one per view, each carrying its team tag. This is where most real crashes get caught, named, and contained. A view blowing up takes down its own screen and reports itself to the right team. The rest of the app keeps running.

There’s a small detail in our dashboard layout that I’m quietly fond of. The route boundary is keyed by the current path:

<ErrorBoundary fallback={<FallbackErrorScreen />} key={getErrorBoundaryKey(pathname)}>
  {/* the routed view */}
</ErrorBoundary>

React remounts a component when its key changes. So when a user lands on a crashed screen, sees the fallback, and clicks away to a different view, the key changes, the boundary remounts, and the error state clears itself. The user navigates out of the wreckage instead of being trapped in it until a hard refresh. Crash recovery, for free, from a prop React already had.

The third layer is the smallest, and it’s where this stops being theory. Our dashboard is a grid of widgets. Each one fetches its own data, lazy-loads its own code, and is fully capable of throwing on its own. If a single misbehaving widget could take down the whole dashboard, the page would be one bad API response away from a white screen.

So every widget gets its own boundary, wrapped right around its Suspense:

<ErrorBoundary
  fallback={<ErrorBoundaryScreen />}
  beforeCapture={(scope) => scope.setTags({ team: Teams.BUSINESS })}
>
  <Suspense>
    <Component {...widgetProps} />
  </Suspense>
</ErrorBoundary>

One widget dies, you get a tidy little “couldn’t load this widget” card in its place. The other eleven widgets don’t even notice. The dashboard stays a dashboard.

Top of the app, you want the net wide and the failure loud. Down at a single widget, you want the net tiny and the failure invisible to everything around it. Same primitive, three sizes, chosen by how much should be allowed to break.

A tag is only worth what the inbox is worth

There’s a part of this that’s easy to skip and shouldn’t be.

A team tag is only useful if team:courses actually means “Courses has a bug to fix.” The moment Sentry fills up with noise, the tags stop meaning anything. A user’s flaky wifi. A browser extension throwing inside your bundle. A 404 from an endpoint that was always going to 404. People start ignoring the channel. And an alert everyone ignores is worse than no alert, because it cost you the effort of building it and gave you nothing back.

So we spend real effort on the front door. Before an error is ever sent, it goes through a filter. Connectivity blips get dropped. The framework’s own known-noisy errors get dropped. Client-side 4xx responses get dropped too. The user asked for something they weren’t allowed to have. That’s not a crash, that’s Tuesday.

beforeSend(event, hint) {
  if (isFramelessStackOverflow(event)) return null;
  const status = getHttpStatus(hint?.originalException);
  if (typeof status === "number" && status > 400 && status < 500) return null;
  return sanitizeErrorEvent(event);
}

Returning null means the event never leaves. It’s a small function with an outsized job. It’s the reason the team tags point at real work instead of pointing at static.

The tagging tells you whose bug it is. The filtering is what makes “whose bug” a question worth answering at all.

What it actually bought us

One more piece of honesty. We didn’t build this from scratch in a vacuum. We’d been leaning on react-error-boundary, the community library, and at some point realized that @sentry/react ships its own ErrorBoundary that already knows how to talk to Sentry’s scope. The beforeCapture hook, the scope, the tagging. All native. So we migrated onto it. One fewer dependency, and a boundary that speaks the language of the tool we were already paying for.

The payoff isn’t dramatic in the way a shiny feature is dramatic. Nobody sends you a thank-you note for an error report that routes itself. But the morning ritual changed. The new issue at the top of Sentry now arrives wearing a team name. You read the tag, you know if it’s yours, and if it isn’t, you move on with your coffee still warm.

The things I’d take from it, if you’re staring at your own pile of anonymous stack traces:

• Catching the error is the easy half. Attributing it is the half you keep doing by hand. It’s rarely hard, just repetitive, and repetitive is exactly what you should hand to the code. Optimize for the question you actually ask at triage: “whose is this?”
• Put ownership where it can’t drift. The routing table already knows which screens exist. Let it be the one place that knows who owns them, too.
• Match the boundary to the blast radius. Wide and loud at the top, tiny and silent around a widget. One primitive, sized to how much is allowed to break.
• Guard the inbox like it’s the product. A tag pointed at noise is worse than no tag. Drop the connectivity blips and the 4xxs before they ever land.

A white screen will always be a bad day for somebody. We didn’t fix that. We just made sure the report knows whose bad day it is, and that it shows up before they do.

Alexander Antoniades, Frontend Chapter Lead
Alexander Antoniades is the Frontend Chapter Lead at TalentLMS. He spends his days obsessing over web performance and front-end architecture — the kind of work where shaving off 50 milliseconds feels …

I want you to picture something. It’s a Tuesday. You’re at your desk. Coffee’s still warm. You open your terminal, bump a version number, hit install, and watch your entire project catch fire.

That’s a React upgrade.

It always sounds straightforward — a quick version bump, npm install, maybe mute a few warnings. But if you’ve actually done it, you know the truth. The version number is the easy part. Everything that comes after is the part nobody warns you about.

A few months back, our Frontend chapter pulled off a full upgrade from React 17 to React 18 during a hackathon at our headquarters in Athens. The whole team, working toward a common goal. It was challenging, messy, and — I’ll admit — actually fun.

React 18 was working fine after that. Life was good. But the ecosystem, it never sits still, does it? Libraries started hinting that React 19 was the “expected” baseline. TypeScript types were drifting in that direction. Deprecation warnings started showing up like passive-aggressive Post-it notes on your monitor.

Nobody wants to be the team still running the old version when the next wave hits. That’s how you end up three versions behind, staring down a rewrite.

So this time, I decided to do it solo. Just me, a codebase, and what I assumed would be a quiet afternoon.

I was wrong.

The Challenges

Dependency Conflicts

Here’s the thing about upgrading React. You’re not upgrading React. You’re upgrading everything that ever touched React.

The moment I bumped to React 19, the whole project started screaming. React Router needed a version bump. Nearly all unit tests failed. Testing libraries demanded newer React DOM APIs. ESLint plugins lost their minds. I thought this would be easier than the 17-to-18 jump. Instead, I was playing whack-a-mole with a cascade of small fires, each one revealing two more underneath.

I thought about quitting. Just reverting the branch, closing the laptop, going for a walk. Pretending none of it happened.

I didn’t. But I thought about it.

The Bugs That Were Always There

Here’s a dirty secret about React upgrades: half the bugs you “discover” aren’t new. They were always there. You just never had a reason to look.

Take this example. On React 18, this effect worked without complaints — reset was replacing the entire form state with just { event: { type } }:

useEffect(() => {
  const preservedEventType = formValuesWatch.event?.type;
  reset({ event: { type: preservedEventType } });
}, [eventTypeWatch]);

It worked. It shipped. Nobody questioned it. But it was broken the whole time. Every time this effect ran, it was throwing away the rest of your form values and replacing everything with a minimal object. React 18’s StrictMode was already double-firing effects in development — which meant this bug was being triggered twice per render cycle. But TypeScript didn’t complain about the shape mismatch, and the form seemed to work, so nobody noticed. Or maybe we just looked the other way.

Then we upgraded to React 19 and updated @types/react. The stricter types lit up like a Christmas tree. Suddenly TypeScript cared about what we were passing to reset(). And once we started looking at the flagged code, the real bug became obvious — this effect had been silently corrupting form state all along. The upgrade didn’t break it. It just ripped off the bandage.

The fix was to stop being lazy about it:

useEffect(() => {
  const preservedEventType = formValuesWatch.event?.type;
  const currentValues = getValues();
  reset({
    ...currentValues,
    event: { ...currentValues.event, type: preservedEventType },
  });
}, [eventTypeWatch]);

Grab the current values. Spread them. Override only what you need. Don’t blow away things you didn’t mean to touch. Simple, once you see it. But you have to see it first — and sometimes it takes an upgrade to force you to look.

TypeScript Got Stricter As Well

This is the part where it gets fun. And by fun, I mean the kind of fun where you open your IDE and every single file has red squiggles. Everywhere. Like your codebase developed a rash overnight.

React 19 shipped with completely overhauled TypeScript types, and the changes were not cosmetic. ReactChild, ReactText, a handful of other utility types you probably used without thinking — gone. Just removed. If your codebase referenced them, even indirectly through a shared component library, you got a wall of errors the moment you updated @types/react.

Then there was the ref situation. React 19 finally lets you pass ref as a regular prop. No more forwardRef wrapping. That’s the good news. The bad news is that on the TypeScript side, ref callback return types got stricter. If you had ref callbacks with implicit returns — an arrow function that accidentally returned something — TypeScript now rejected them. Across a large codebase, these “small” changes multiplied into hundreds of type errors.

useRef got pickier too. Call it without an argument? TypeScript error. You need to explicitly pass null or undefined now. RefObject no longer includes null by default, so any code that assumed ref.current could be null needed touching.

The React team published a codemod (types-react-codemod) that handled some of this. The keyword being some. The more custom your type patterns, the more you were on your own.

The forwardRef Farewell

This one deserves its own section because it touched everything.

With React 19 treating ref as a regular prop, forwardRef becomes unnecessary. In theory, that’s a beautiful simplification. In practice, we had dozens of components wrapped in forwardRef, each with its own generic type signatures, its own quirks, its own reasons for existing.

Removing forwardRef meant restructuring every single one. Pull ref into the props interface. Update the type signatures. Make sure the parent components that pass refs still compile. It was mechanical, repetitive, mind-numbing work — the kind where you get sloppy on component number 47 because your eyes have gone glassy and everything looks the same.

The kind of work that breaks you if you let it.

Enter Claude Code

A few hours in. Buried in type errors. Tests failing everywhere. That quiet voice in your head saying this solo upgrade was a terrible idea.

That’s when I decided to throw Claude Code at it.

I’d used it before for smaller things — generating boilerplate, explaining someone else’s code, the usual. But I’d never thrown it at a full-scale migration. A real mess. The kind of mess where you don’t even know where to start.

Turns out, that’s exactly where it comes alive.

Bulk Code Migrations

The forwardRef removal was the first real test. Dozens of components. All needing the same structural surgery: unwrap forwardRef, move ref into the props type, clean up the generics. By hand, this is the kind of task that takes hours and introduces bugs at a steady, reliable rate.

With Claude Code, I described the pattern once. It understood the structure. And then it just… did it. Across the codebase.

What got me was how it adapted. It didn’t do a dumb find-and-replace. Components with complex generic types got different treatment than simple ones. It caught cases where ref was being used in non-standard ways and flagged them for manual review instead of blindly transforming them. It was thinking about the code, not just processing it.

Same approach worked for the deprecated type references. Every instance of ReactChild that needed to become React.ReactElement | number | string? Handled. File by file. Respecting existing imports. Not introducing noise.

Debugging Type Errors

This is where Claude Code really earned its place. After the bulk migrations, I still had a backlog of type errors that weren’t mechanical. Nuanced things — useReducer inference changes, ref callback return types, third-party library type mismatches.

Normally, each of these is a 20-minute rabbit hole. Google the error. Find a GitHub issue from eight months ago. Read through 40 comments to find the one that actually has the answer. Try three different approaches. Repeat.

Instead, I could feed Claude Code the error and the surrounding code and get back a clear explanation of why it broke and how to fix it. Not just “change this line.” It understood the difference between “this broke because React 19 changed the type definition” and “this was always wrong, React 18 just let you get away with it.”

One that sticks out: we had a custom hook that returned a ref callback. After the upgrade, TypeScript hated the return type. Claude Code immediately identified the issue — React 19 introduced ref cleanup functions, so you can now return a cleanup function from a ref callback, similar to useEffect. The implicit return in our arrow function was being interpreted as a cleanup function. The fix was a one-liner. Add explicit curly braces. Done.

Understanding why that was the fix? That would have cost me half an hour on my own. Maybe more.

Fixing Broken Tests

Nearly all our unit tests were failing. This was probably the most daunting part, because test failures are a special kind of demoralizing — you can’t tell at a glance whether it’s a real problem or just noise from the upgrade.

The failures fell into categories. Testing library API changes. StrictMode behavior affecting test output. Genuine regressions from our refactoring. The tricky part is figuring out which is which.

Claude Code helped me triage at speed. Feed it a failing test with its error output. It would tell me: this is a testing library compatibility issue (update @testing-library/react, adjust the assertions), this is a StrictMode double-render thing (your test was relying on render count), this is an actual bug you introduced (fix it).

For the testing library issues, it helped me batch-update patterns across the entire test suite. Replacing deprecated query methods. Updating async utilities. Adjusting mock setups that assumed React 18 rendering behavior. The boring, necessary work that eats your day if you do it by hand.

What I Learned

A few things I’m taking away from this:

Upgrade to 18.3 first. If you haven’t already, install react@18.3 before you even think about 19. It’s identical to 18.2 but adds deprecation warnings for everything that will break. Think of it as a damage report before the actual damage.

Don’t underestimate the type changes. The runtime breaking changes in React 19? Manageable. The TypeScript type changes? That’s where the real volume lives, especially in a large codebase. Run the official types-react-codemod early — it won’t catch everything, but it’ll clear the surface-level wreckage. And if you’re on a large project and can’t afford to fix every type error in one go, look into Betterer . It lets you snapshot your current type errors and enforce that things only get better over time — no new errors allowed, but existing ones can be chipped away incrementally across PRs. Merge the upgrade, unblock your team, and clean up at your own pace. No shame in that.

The upgrade didn’t break your code. It exposed what was already broken. Half the bugs we found during the migration existed in React 18 too — we just never had a reason to look. Stricter types forced us to revisit code we hadn’t touched in months, and that’s where the real issues were hiding. Don’t blame the upgrade. Thank it.

AI tooling has crossed a line for migrations. I’ll be honest — I was skeptical. Migrations aren’t about writing new code. They’re about understanding why existing code breaks under new rules and applying the right fix without creating new problems. That felt too nuanced for an AI tool. I was wrong. Claude Code didn’t replace my judgment, but it cut the mechanical work and research time dramatically. The ratio shifted from “90% investigation, 10% fixing” to something much more sane.

Final Thoughts

Would I do the solo upgrade again? Yes. But only because Claude Code made it possible. Without it, this would have been days of documentation, GitHub issues, and Stack Overflow threads. The kind of work that makes you question your career choices.

Instead, it was one intense session where I could focus on the decisions that actually mattered and hand off the repetitive, soul-crushing investigation work to something that didn’t mind doing it.

The React ecosystem keeps moving. These upgrades aren’t optional forever. You put them off, they compound. The gap gets wider. The next upgrade gets worse.

The good news? The tooling for managing migrations — from the React team’s codemods and incremental releases, to AI assistants that actually understand what they’re looking at — is getting better, fast.

If you’ve been sitting on the React 19 upgrade, my advice is simple: stop waiting. It’s not going to get easier on its own. Grab the best tools you have and start pulling the thread.

Your future self will thank you. Or at least stop resenting you.