At the end of the last article I said that once you hold one coherent copy of server state and can invalidate it precisely, a door opens that used to be terrifying: updating the UI before the server confirms, and rolling back cleanly if it rejects. That's optimistic UI, and I want to be honest about what it actually is before we make it feel magic.

Optimistic UI is a lie. A small, well-intentioned, usually-correct lie — but a lie. You click the star, and the star fills in immediately, before the server has any idea you did anything. You're betting the request will succeed and showing the user the future you expect. Most of the time you're right and the app feels instant. The entire craft is in what happens the rare time you're wrong.

Why we bother lying at all

The alternative is honest and awful. User clicks, you show a spinner, you wait for the round trip, then you update. On a good connection that's 200-400ms of the UI sitting there doing nothing after a click that should have felt instant. On a train, it's two seconds of a spinning star. For a like button, a toggle, a reorder — high-frequency, low-stakes actions — that latency is the whole experience, and it makes a fast app feel slow.

So we front-run the server. The user's intent is almost always going to succeed, so we render success now and reconcile with reality when it arrives. The feeling is immediate; the correctness catches up a beat later.

Optimistic UI is a promise to the user: "I'll show you this now, and I guarantee I'll fix it if I was wrong." If you can't keep the second half, don't make the first.

The dangerous naive version

Here's the version I see most often, and it's the one that ships bugs:

// DON'T: optimism with no way back
function useToggleStar(id: number) {
  const [starred, setStarred] = useState(false);
  const toggle = async () => {
    setStarred((s) => !s);        // update immediately
    await api.setStar(id, !starred); // hope it works
  };
  return { starred, toggle };
}

Read what happens when api.setStar throws. The state already flipped. There's no snapshot, no catch, no rollback. The star stays filled, the server never recorded it, and the user walks away believing they starred something they didn't. This isn't a cosmetic bug — the UI is now actively lying with no plan to stop. Optimism without rollback isn't optimistic UI. It's just a race you're pretending you won.

The real shape: snapshot, apply, reconcile

A correct optimistic update always has the same four beats. Cancel anything in flight that could clobber you. Snapshot the current truth. Apply the optimistic change. Then, when the request settles, either keep it (success) or restore the snapshot (failure). Because this series uses TanStack Query, the cache is where the truth lives, and the mutation lifecycle gives you exactly these hooks:

const toggleStar = useMutation({
  mutationFn: (id: number) => api.toggleStar(id),

  onMutate: async (id) => {
    // 1. stop in-flight refetches so they can't overwrite our optimistic value
    await queryClient.cancelQueries({ queryKey: ['todo', id] });

    // 2. snapshot the current truth so we can roll back
    const previous = queryClient.getQueryData<Todo>(['todo', id]);

    // 3. apply the optimistic change to the cache
    queryClient.setQueryData<Todo>(['todo', id], (old) =>
      old ? { ...old, starred: !old.starred } : old,
    );

    // hand the snapshot to onError via context
    return { previous };
  },

  onError: (_err, id, context) => {
    // 4a. reality rejected us — restore exactly what we had
    if (context?.previous) {
      queryClient.setQueryData(['todo', id], context.previous);
    }
  },

  onSettled: (_data, _err, id) => {
    // 4b. reconcile with the server's version, success or failure
    queryClient.invalidateQueries({ queryKey: ['todo', id] });
  },
});

Every line earns its place. cancelQueries is the one people skip and then can't explain the flicker: if a background refetch is already in flight, it will land after your optimistic write and stomp it with stale data. Snapshotting into context is what makes rollback surgical — you restore the exact previous object, not a guess. And onSettled invalidating is the humility step: whatever we optimistically showed, the server's answer is the real one, so we refetch and let truth win. This is why the previous article's precise invalidation mattered — optimistic UI is built directly on top of it.

Reconciliation is not "did it work" — it's "what's true now"

The subtle part is the reconcile step, because the world is not just success-or-failure. Sometimes the request succeeds but the server's result differs from what you optimistically drew. You optimistically added an item at the top of a list; the server inserts it sorted, so it's actually third. You optimistically set a counter to 5; someone else's change already made it 7.

The rule that keeps you sane: the server is the source of truth, and reconciliation means adopting its version, not defending yours. Your optimistic value was a placeholder to make the UI feel alive, nothing more. When the real data arrives, you replace the placeholder — even if it means the item you just "added to the top" visibly jumps to its sorted position. That tiny correction is honest and fine. Fighting to keep your optimistic guess because it looks smoother is how you end up with a client that slowly drifts out of sync with the backend.

Where it belongs, and where the lie gets expensive

I reach for optimistic UI when the action is cheap, reversible, and frequent, and when being wrong is cheap to correct. Toggling a star, liking a post, checking a checkbox, reordering a list, adding a comment. If the request fails, the rollback is a small, understandable flicker, and the user retries. The upside — instant feel — is huge and constant; the downside is rare and mild.

I do not reach for it when a wrong guess is expensive or confusing. Payments are the obvious one: never optimistically show "Payment successful." Showing success for a charge that then fails is worse than any spinner. Same for anything irreversible, anything with legal or money weight, and anything where the rollback would be more jarring than the wait — imagine optimistically navigating someone into a screen that then vanishes because the action failed. In those cases the honest spinner is the right call. The question isn't "can I make this optimistic?" It's "if I'm wrong, is the correction cheap and clear?" When the answer is no, don't tell the lie.

The reframe

What optimistic UI really taught me is that a good client models intent and confirmed truth as two different things, and knows how to move between them. The optimistic value is intent rendered early. The server response is confirmed truth. Reconciliation is the bridge. Once you hold those as separate ideas, the whole pattern stops feeling like a hack and starts feeling like what it is: a disciplined way to decouple how fast the UI feels from how fast the network actually is.

And notice what the rollback in onError really was — a single-step reversal back to a snapshot you took a moment ago. That works beautifully for one action. But the moment users want to reverse a sequence of actions — undo the last five edits in an editor, then redo two of them — a lone snapshot isn't enough. You need a history of reversible changes, which is a different and genuinely interesting problem. That's undo/redo, and it's next.

If you've got an optimistic update in your app right now, do me a favor and check one thing: what happens on onError? If you can't point to the line that restores the previous value, you don't have optimistic UI — you have a lie with no exit. Tell me what you find.

The previous article drew a hard line: state the client owns versus data it doesn't. Everything there was about the stuff you own — theme, drafts, preferences — where you are the source of truth and storage just remembers it. This one is about the other side of that line, and it's where a lot of otherwise-clean apps quietly turn to mush.

Here's the situation. You fetch a list of customers for a table. You fetch one customer for a detail page. There's a little avatar-and-name badge in the header showing the currently selected customer. That's three network responses. And customer #42 appears in all three. You now have three copies of one entity in memory, and — this is the part that bites — nothing keeps them in agreement. Edit the customer's name on the detail page, and the table still shows the old name until something refetches it. The badge shows a third version. Your UI is now lying to the user, and the bug report says "the name didn't update," which tells you nothing about why.

This is the server-state problem, and it is fundamentally different from the local-state problem. You don't own this data. It has an owner on the backend. Every copy you hold is a cache of a truth that lives somewhere else and can change without telling you.

The duplication trap

The instinct is to treat each fetch as its own little pile of data. List query returns an array, you render it. Detail query returns an object, you render it. Header does its own thing. Each is correct in isolation. The problem is that the same entity is now stored in multiple unrelated places, and a write to one has no path to the others.

The bug isn't that data goes stale. It's that you have more than one copy of the same truth, and no single place responsible for it.

There are two honest ways out, and picking the wrong one is where teams either over-engineer or under-engineer for years.

Option one: normalize into one source of truth

Normalization is the database idea, moved into the client. Instead of storing whatever shape each response happened to have, you break responses into entities keyed by id, store each entity exactly once, and have every view reference it by id.

// denormalized — the same customer duplicated across responses
const listResponse = [{ id: 42, name: 'Acme Corp', tier: 'gold' }, /* ... */];
const detailResponse = { id: 42, name: 'Acme Corp', tier: 'gold', notes: '...' };

// normalized — one customer, referenced by id
const cache = {
  customers: {
    42: { id: 42, name: 'Acme Corp', tier: 'gold', notes: '...' },
  },
  // the list is now just an ordered array of ids into the store above
  customerList: [42, 17, 8],
};

Now there is exactly one customers[42]. The table reads customerList and looks each id up. The detail page reads customers[42]. The header badge reads customers[42]. Update that one record and every view re-reads the same object — they can't disagree, because there's nothing to disagree with. This is what normalized caches like RTK Query, Apollo, and the normalizr-style approach give you: a mini in-memory database where entities live once and views are just queries into it.

The cost is real, though, and it's why I don't reach for it by default. You need an identity for everything (what's the id? what about entities without one?), you need to teach the cache how to normalize each response shape, and nested relationships get fiddly. You've essentially adopted a client-side ORM. For a CRM-scale app with heavy entity reuse and live updates, that's a good trade. For most apps, it's a lot of machinery for a problem you can solve more cheaply.

Option two: let the query cache own it, invalidate precisely

The cheaper answer — and the one this series defaults to, because it uses TanStack Query — is a document cache rather than a normalized one. Data is cached per query key, not per entity. ['customers'] is one cache entry; ['customer', 42] is another. There genuinely are two copies of customer #42. The trick is that you don't try to keep them manually in sync — you make the cache re-fetch the affected keys after a change, and you do it surgically.

The blunt instrument everyone reaches for first:

// after editing a customer — refetch literally everything customer-related
await queryClient.invalidateQueries();

This "works" and it's a performance and UX disaster. Every table, every dropdown, every cached query on the screen refetches, spinners bloom everywhere, and you've turned one edit into a network storm. Invalidation is not a hammer. It's a scalpel:

const mutation = useMutation({
  mutationFn: updateCustomer,
  onSuccess: (updated) => {
    // 1. patch the detail cache directly — no refetch needed, we have the data
    queryClient.setQueryData(['customer', updated.id], updated);

    // 2. mark just the list stale, so it refetches when next observed
    queryClient.invalidateQueries({ queryKey: ['customers'], exact: true });
  },
});

Two precise moves. setQueryData writes the fresh entity straight into the detail cache, so the detail page updates instantly with zero network. invalidateQueries with a specific key marks only the list as stale — and critically, TanStack Query won't even refetch it until something is actually looking at it. Nothing else on the page moves. That precision is the whole skill. The library gives you a scalpel; most bugs come from swinging it like a hammer.

The mental shift: query keys are your schema

Here's the reframe that made this click for me. In a normalized cache, your entity ids are the schema — everything hangs off customers[42]. In a document cache, your query keys play that role. The structure and discipline of your query keys is what makes precise invalidation possible or impossible.

If your keys are ad hoc — ['customers'] here, ['customerList', filters] there, ['allCustomers'] in a third place — you can't invalidate precisely because you can't describe the set of things that went stale. But if keys are hierarchical and consistent, invalidation becomes expressive:

// a consistent, hierarchical key factory
const customerKeys = {
  all: ['customers'] as const,
  lists: () => [...customerKeys.all, 'list'] as const,
  list: (filters: Filters) => [...customerKeys.lists(), filters] as const,
  details: () => [...customerKeys.all, 'detail'] as const,
  detail: (id: number) => [...customerKeys.details(), id] as const,
};

// invalidate every customer list, regardless of filters, and nothing else
queryClient.invalidateQueries({ queryKey: customerKeys.lists() });

Because TanStack Query matches keys by prefix, customerKeys.lists() invalidates every filtered list variant in one call without touching a single detail cache. The key factory turns "which things are now stale" into a sentence you can write. This is the same instinct as a good public API or module boundary: a little structure up front makes the operations you'll do a thousand times both possible and safe.

How to actually choose

I'll be direct, because this is where people waste the most effort. Reach for a normalized cache when three things are true together: the same entities are reused heavily across many views, they update frequently (real-time, collaborative, or lots of mutations), and staleness between views is genuinely user-visible and unacceptable. Trading dashboards, chat apps, collaborative editors, big CRMs — normalization earns its keep there.

For everything else — which is most apps — a document cache with disciplined query keys and precise invalidation is not a compromise, it's the right call. It has less machinery, less to learn, fewer ways to corrupt the cache, and it scales further than people expect. Honestly, the number of teams who adopted a full normalized cache and then used it like a document cache anyway is not small. Start with the simpler model and let real pain — not anticipated pain — push you to the heavier one.

Either way, the principle underneath both is identical, and it's the thing to actually remember: there is one truth, it lives on the server, and your job is to hold one coherent copy of it — not five copies you hope agree. Normalization enforces that with entity ids. A query cache enforces it with keys and invalidation. Pick your mechanism, but don't skip the principle, because "the name didn't update" is what skipping it looks like in the bug tracker.

Once you've got one coherent copy and precise invalidation, a door opens that used to be terrifying: updating the UI before the server confirms, and rolling back cleanly if it rejects. That's optimistic UI, and it's only sane once your cache has a single source of truth to optimistically edit and a precise way to reconcile when the truth comes back. That's next.

If your app has a "why is this showing the old value" bug right now, I'd bet it's a duplication problem wearing a staleness costume. Tell me where the copies live — list and detail, cache and store, two tabs — and I'll tell you which of these two models you actually needed.

At the end of the last article I said I wanted to start this run with the deceptively simple persistence question: what belongs in localStorage, what belongs in state, and what breaks when you pretend they're the same thing. It sounds like a beginner question. It isn't. I've seen senior codebases get this wrong in ways that produce flickering UIs, tabs that overwrite each other, and a crash the first time someone ships a new version of the app.

The root mistake is almost always the same, and it's a framing problem. localStorage looks like a global variable that happens to survive a refresh. localStorage.getItem('theme') reads like window.theme. So people start treating it as a place to keep state — reading from it in render, writing to it inline, scattering getItem/setItem across components. That framing is the bug. Everything downstream goes wrong because of it.

Three concerns people mash into one

When someone says "I'll just store it in localStorage," they're usually blending three separate things that have nothing to do with each other:

Source of truth — where the current value lives right now, in memory, reactive, driving the UI. That's your state (a store atom, context, useState).

Persistence — how that value survives a reload. That's storage: localStorage, IndexedDB, a cookie.

Cross-tab sync — how two open tabs agree on the value. That's a messaging problem.

localStorage can only honestly do the middle one. It is not reactive — writing to it doesn't re-render anything. It is synchronous and string-only. And it's shared across tabs in a way that will surprise you. The moment you ask it to be your source of truth, you've handed the hardest job to the tool least suited for it.

Storage is a mirror of your state, not the state itself. The state lives in memory and drives the UI; storage just remembers what it was so you can restore it later.

Once that sentence is the rule, the architecture falls out of it. State is the thing components read and write. Storage is a side effect: you hydrate from it once at startup, and you persist to it when state changes. Components never touch storage directly.

The render-time read that breaks SSR

Here's the most common concrete failure, and it's worth seeing clearly. Someone initializes state straight from storage:

// looks fine, quietly broken
function useTheme() {
  const [theme, setTheme] = useState(localStorage.getItem('theme') ?? 'light');
  // ...
}

On a purely client-rendered app this mostly works. On anything server-rendered — Next.js, which is what this whole series builds on — it detonates two ways. First, localStorage doesn't exist on the server, so the render throws. Second, even if you guard it, the server has no idea what's in the user's storage, so it renders light, the client hydrates with dark, and React screams about a hydration mismatch — or worse, silently flips the UI after paint. That flash of the wrong theme is the visual signature of "someone read storage during render."

The fix follows directly from the mirror rule. Render from state with a stable default, then hydrate from storage in an effect, after the first paint:

function useTheme() {
  const [theme, setThemeState] = useState<'light' | 'dark'>('light');

  // hydrate once, on the client only
  useEffect(() => {
    const stored = localStorage.getItem('theme');
    if (stored === 'light' || stored === 'dark') setThemeState(stored);
  }, []);

  const setTheme = useCallback((next: 'light' | 'dark') => {
    setThemeState(next);
    localStorage.setItem('theme', next); // persist as a side effect
  }, []);

  return [theme, setTheme] as const;
}

Server and client both start at light, so hydration matches. The stored value takes over a tick later. If the theme flash bothers you, that's a real concern — but you solve it with a tiny inline script in the document head that sets a class before React boots, not by reading storage during React's render. The two problems stay separate.

Persist the store, not a hundred components

Doing this hook-by-hook gets old fast, and it scatters setItem calls everywhere — which is exactly the kind of smeared side effect that makes a codebase hard to reason about. Since this series uses Reatom for state, persistence belongs at the store layer, as one declarative concern, not a hundred manual writes.

import { atom } from '@reatom/core';
import { withLocalStorage } from '@reatom/persist-web-storage';

// the atom is the source of truth; localStorage is a declared mirror of it
export const themeAtom = atom<'light' | 'dark'>('light', 'themeAtom').pipe(
  withLocalStorage('theme'),
);

Now the atom is where the value lives and where the UI reads it. The persistence adapter mirrors every change to localStorage and rehydrates on load — including, importantly, listening for changes from other tabs. You wrote zero getItem/setItem calls. The concern lives in one place you can see, test, and change. This is the same principle from the composition and DI article: don't let components reach out and grab infrastructure; hand it to them, or push it to a layer that owns it.

Two tabs, one storage, a fight

The surprise that catches people: localStorage is shared across every tab on the same origin. Open your app in two tabs, change the theme in one, and the other tab's in-memory state has no idea. Its localStorage updated underneath it, but React state didn't move. The two tabs now disagree, and whichever one writes next wins, clobbering the other.

The browser gives you exactly one tool for this — the storage event, which fires in other tabs (never the one that made the change):

useEffect(() => {
  const onStorage = (e: StorageEvent) => {
    if (e.key === 'theme' && (e.newValue === 'light' || e.newValue === 'dark')) {
      setThemeState(e.newValue);
    }
  };
  window.addEventListener('storage', onStorage);
  return () => window.removeEventListener('storage', onStorage);
}, []);

A good persistence adapter (like Reatom's above) already does this for you, which is another reason to centralize it. But you should know the event exists, because the "tabs fight each other" bug is invisible in development — you almost never have two tabs open while coding — and then very visible in production. If tab sync actually matters for your feature, BroadcastChannel is the more deliberate tool; storage is the free one you get for persisting at all.

Versioning: the crash that ships with v2

Here's the failure that only shows up after you succeed. You persist a settings object. Months later you change its shape — rename a field, split one setting into two. You deploy. Every returning user's browser hydrates the old shape into code that expects the new shape, and something reads settings.notifications.email on an object where notifications is now a string. Crash. On load. For existing users only — which is why your testing missed it.

Persisted data is data you shipped in the past, running against code you shipped today. It needs a version and a migration path, exactly like a database:

type StoredSettings = { version: number; theme: 'light' | 'dark'; density: 'cozy' | 'compact' };

function loadSettings(): StoredSettings {
  const raw = localStorage.getItem('settings');
  const parsed = raw ? JSON.parse(raw) : null;

  // no data, or an old shape we no longer trust → start clean
  if (!parsed || parsed.version !== 2) {
    return { version: 2, theme: 'light', density: 'cozy' };
  }
  return parsed;
}

Reject-and-reset is the cheapest correct answer for preferences — losing someone's theme choice is not a tragedy. For anything you can't throw away, write real migrations keyed on version. Either way, the non-negotiable part is: never trust the shape of persisted data. It came from a version of your app you don't control anymore.

So what actually goes in there

Pulling it together, the fit test is simple: store things the client owns and the client alone can restore. Theme and UI preferences. Sidebar collapsed or expanded. A draft of a form the user hasn't submitted. The last route they were on. Small, client-owned, non-sensitive, and fine to lose in the worst case.

What doesn't belong: anything sensitive (localStorage is readable by any script on the page — a token there is a token exposed to every XSS), anything large (multi-megabyte blobs want IndexedDB, which is async and built for size), and — the big one — server data. The list of customers, the current user's profile, the order you just fetched: that data is not yours. It has an owner on the backend, and your copy is a cache, not a persisted preference. Stuffing it into localStorage means you now have two stale copies fighting instead of one.

And that's the seam into the next article. Everything here was about state the client owns — you're the source of truth, storage just remembers it. Server state flips that on its head: the source of truth lives somewhere else, the same entity shows up in five different responses, and "persistence" stops being the problem while "which copy is correct" becomes it. That's data normalization and cache invalidation, and it's where a lot of otherwise-clean apps quietly turn to mush.

If you've got a persistence bug you can't quite pin down — a flash on load, a tab that resets another, a crash that only hits returning users — tell me the symptom. Nine times out of ten it traces straight back to treating storage as state, and I'd like to hear the tenth.

The hardest part of a UI kit is not writing the components. That's the trap. You can build a clean <Button>, a flexible <Select>, a beautiful <Modal>, publish them to a package, and feel like the system exists. Then six months later one app is on version 1.4, another is on 2.1, a third has copied half the styles locally, and everyone is scared to upgrade because nobody knows what will break.

At that point the UI kit did not fail as a component library. It failed as a product.

The previous article was about changing a shared component inside one codebase, where you can grep every call site and run a codemod yourself. This is the harder version: several applications consume the kit as a versioned package. You can't see every usage. You can't update every app in one pull request. You can't assume every team upgrades on the same day. So the question changes from "how do I make the component better?" to "how do I make upgrades safe enough that people keep taking them?"

That's the real work.

A UI kit is not shared until upgrades are routine

A lot of teams treat "published package" as the finish line. It isn't. A package can be shared and still be effectively frozen. If every upgrade requires a migration meeting, manual QA across five apps, and someone brave enough to merge first, the kit is not healthy. It's a museum.

The signal I care about is boring: can an app upgrade from 2.3.1 to 2.3.2 on a normal Tuesday without drama? Can it take a minor version without reading every diff? Can it delay a major version without blocking everyone else? If the answer is yes, the UI kit is alive. If the answer is no, every improvement you make piles up behind the same wall: adoption risk.

A design system is only as real as its upgrade path. If people cannot safely move to the next version, the new version mostly exists in your repository.

This is why "one version everywhere" is a nice goal and a terrible starting assumption. You may want every app on the latest version. You probably should. But the mechanism that gets you there is not hope. It's compatibility, contracts, release discipline, and migration support.

Semver is a promise, not a decoration

Version numbers are not vibes. They are a communication system between the kit and every app that depends on it. If you treat them casually, people stop trusting them.

The contract is simple:

{
  "name": "@company/ui-kit",
  "version": "2.4.0"
}

A patch release fixes bugs and should be safe. A minor release adds capabilities without breaking existing usage. A major release may require changes, and the migration path must be explicit. That's semver on paper. In practice, the hard part is being honest about what counts as breaking.

Changing a prop type is obviously breaking. Removing a component is breaking. But so is changing keyboard behavior in a menu. So is changing focus trapping in a modal. So is changing the DOM structure if consumers style nested elements, even if you wish they didn't. So is renaming a CSS variable that apps rely on. UI libraries have more contracts than TypeScript can see.

That means the rule has to be conservative: if a reasonable consumer could notice the change in code, behavior, accessibility, or visual output, treat it as a contract change. Maybe it's still worth doing. Just don't smuggle it into a patch release and call the upgrade safe.

Public API must be smaller than the folder tree

This connects directly back to the barrel files article. A UI kit needs a public API, but that API has to be intentional. If apps can import from anywhere inside the package, every internal file becomes a promise you didn't mean to make.

Bad shape:

import { Button } from '@company/ui-kit/src/components/button/button';
import { buttonRecipe } from '@company/ui-kit/src/components/button/styles';
import { useModalMachine } from '@company/ui-kit/src/internal/modal-machine';

Now your internal structure is part of the external contract. You can't reorganize files. You can't swap the modal implementation. You can't rename a style recipe. The consuming apps have turned your source tree into their API.

Good shape:

import { Button, Dialog, Select } from '@company/ui-kit';
import { useCombobox } from '@company/ui-kit/headless';
import { tokens } from '@company/ui-kit/tokens';

Three doors. Components, headless behavior, tokens. Everything else is private. If someone needs a new door, you add it intentionally. You don't let them crawl through a window because the import path happened to work.

In package terms, that means using exports to make the boundary real:

{
  "name": "@company/ui-kit",
  "exports": {
    ".": "./dist/index.js",
    "./headless": "./dist/headless/index.js",
    "./tokens": "./dist/tokens/index.js"
  }
}

This is a small detail with a large consequence. You can only version what you control. A tight public API gives you something finite to protect.

Contract tests are how apps talk back

The uncomfortable part of maintaining a UI kit across apps is that unit tests inside the kit are not enough. They tell you your component works according to your assumptions. They do not tell you whether the apps use it in ways you forgot to protect.

The answer is not to pull every application into your test suite. That turns the kit into a build-system hostage. The better answer is a thin layer of contract tests: small fixtures that represent the promises the kit makes to consumers.

// contracts/dialog.contract.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Dialog } from '@company/ui-kit';

it('keeps focus inside the dialog until it closes', async () => {
  render(
    <Dialog open title="Delete customer">
      <button>Cancel</button>
      <button>Delete</button>
    </Dialog>,
  );

  await userEvent.tab();
  expect(screen.getByRole('button', { name: 'Cancel' })).toHaveFocus();

  await userEvent.tab();
  expect(screen.getByRole('button', { name: 'Delete' })).toHaveFocus();
});

That test is not checking implementation. It is checking a consumer-visible promise: focus stays inside the dialog. If you rewrite the internals from one focus-trap library to another, the contract should still pass. If it doesn't, you didn't make a refactor. You changed behavior.

You need contracts in four layers:

Type contracts. A small TypeScript test project that imports the public API the way apps do. If exported types break, the kit fails before publishing.

Behavior contracts. Testing Library tests for keyboard behavior, focus, ARIA, controlled/uncontrolled state, and callback order.

Visual contracts. Storybook or fixture pages with visual regression on the stable states: default, hover, disabled, loading, error, long text, right-to-left if you support it.

Token contracts. Tests that verify CSS variables and design tokens still exist with expected names. Tokens are API. Treat them that way.

Not every component needs all four layers. A plain Badge probably needs visual and token coverage. A Combobox needs behavior and accessibility coverage badly. The point is to test the promises consumers depend on, not every internal branch.

Release channels keep risk from spreading

If every release goes straight to latest, your first consumer becomes the canary whether they agreed to it or not. That's not fair to them, and it trains people to wait. A better release flow gives the kit a place to be wrong before the stable version moves.

For example:

# experimental builds for early adopters
npm publish --tag next

# stable builds after contracts and canary apps pass
npm publish --tag latest

The next tag is where breaking work, risky rewrites, and big visual changes can be tested by one or two willing apps. latest is the calm channel. It should feel boring. If a team installs latest and gets surprise churn, they will stop trusting the kit. And when trust goes, adoption goes with it.

This does not require a huge platform. Start with one canary app — ideally the app that uses the kit heavily and has the fastest feedback loop. Upgrade it first. Run its smoke tests. Look at the core screens. Fix the kit before asking everyone else to move. The canary app is not there to prove the kit is perfect. It is there to catch the obvious problems while the blast radius is still small.

Migration support is part of the feature

A breaking release without a migration path is not a release. It's homework assigned to every consuming app.

If you remove Button color in favor of Button intent, the release should include more than a changelog sentence. It should include the same tools from the previous article, but packaged for consumers who live outside your repo:

{
  "scripts": {
    "migrate:ui-kit": "npx @company/ui-kit-codemods button-color-to-intent src"
  }
}

The codemod can ship as a small companion package. The migration guide should show old usage, new usage, edge cases, and what the script can and cannot fix. The deprecation should exist for at least one minor cycle before the major removal, unless the old behavior is actively dangerous. And the major release should be boring precisely because the hard work already happened while the old API still existed.

Honestly, this is where many UI kits lose people. The maintainers ship a clean new API and assume consumers will be grateful. Consumers look at their backlog, see forty files to touch, and pin the old version for another year. The new API may be better, but the upgrade experience is worse, so nobody moves.

Documentation has to be versioned too

One small but painful failure mode: the documentation shows the latest version, but half the apps are still on an older one. A developer opens the docs, copies an example, and the prop doesn't exist. Now the UI kit feels broken even though the app is just behind.

If multiple apps can be on different versions, the docs need to acknowledge that reality. At minimum, every docs page should clearly say which version it describes. Better: keep versioned docs for major versions, or at least preserve migration pages long after the release goes out. A migration guide is most useful six months after you wrote it, when the last app finally upgrades.

This also applies to design tokens and screenshots. If your docs render from the latest package but an app is on v2, the visual examples can lie. Sometimes that's acceptable. Sometimes it creates bugs. Be explicit either way.

The rule I use: optimize for trust

There are many tactical choices here — monorepo or separate repo, Changesets or semantic-release, Storybook or Ladle, visual regression provider A or B. Those choices matter, but they're not the center. Trust is the center.

Trust means a patch release doesn't redesign the app. Trust means a minor release doesn't remove a prop. Trust means a major release comes with a migration path. Trust means public imports stay public and private imports are actually blocked. Trust means if a component's behavior changes, there is a test that calls it a behavior change. Trust means teams believe the kit maintainers are trying to make upgrades smaller, not throw work over the wall.

Once that trust exists, you can improve the UI kit continuously. Without it, every improvement becomes suspicious. People fork. They pin. They copy styles locally. They build one-off replacements because waiting for the shared kit feels slower than escaping it. That is how a design system dies: not from one bad component, but from a long series of upgrades people chose not to take.

This closes the component-patterns run: compound components for structure, headless components for behavior, incremental migration inside one repo, and now versioned upgrades across many apps. Next I want to move into state and data at scale, starting with the deceptively simple persistence question: what belongs in local storage, what belongs in global state, and what breaks when you pretend they're the same thing.

If your UI kit is stuck on an old version somewhere, I'm curious what the real blocker is. Is it semver trust, missing migration tools, visual regression fear, or just nobody owning the upgrade? Send me the ugly reason. That's usually where the architecture lives.

At the end of the last article I told you to go find the one component everyone reimplements slightly differently. So let's say you found it. You know exactly how it should work now. There's just one problem: a hundred files already import the old one, and half of them belong to teams you've never met.

This is the part of building shared components nobody puts on the roadmap. Writing the new <Button> is the easy 10%. The other 90% is every place that already calls the old <Button>, and the very specific fear that comes with editing code you don't own to fix a component that, technically, still works. That fear is why so many "we'll clean this up later" components never get cleaned up. The change isn't hard. Changing it everywhere, safely, without a flag day is hard.

So this article isn't about how to design a better component. It's about how to move an existing one forward when it already has dozens of dependents — deprecation paths, codemods, and the discipline that lets you touch a hundred call sites without holding your breath.

The big-bang rewrite is the trap

Here's the instinct I have to talk teams out of constantly. You look at the old component, you see everything wrong with it, and you decide to rewrite it properly on a branch. Two weeks later that branch has touched sixty files, it's three hundred commits behind main, every rebase is a knife fight, and the only way to land it is a single terrifying merge that changes everything at once. If anything breaks — and something always breaks — you can't tell which of the sixty changes did it.

That's a flag day: a moment where the whole codebase has to flip from old to new simultaneously. Flag days feel decisive and they are almost always a mistake. The problem isn't your ability to write the new component. The problem is that you tried to break and rebuild in the same step, so there's never a moment where the system is in a known-good state. You're either fully migrated or fully broken, with nothing in between.

The fix is to refuse the whole framing. You don't rewrite. You evolve.

You never break and rebuild in one step. You add the new path, move callers over one at a time, then delete the old path. Three boring, reversible steps instead of one heroic irreversible one.

That shape has a few names — parallel change, expand/contract, the strangler pattern — but at the component level it's just this: expand the component so old and new both work, migrate the call sites gradually, then contract by removing the old way once nothing uses it. Every intermediate state ships. Every step is revertible on its own. Nothing has a flag day.

Step one: make the change additive

The whole strategy depends on old and new coexisting for a while. So the first move is to add the new API next to the old one instead of replacing it. Say I'm moving a <Button> from a raw color prop to a semantic intent prop — because color="green" tells you nothing about why it's green, and the theme can't remap it.

The tempting move is to rename color to intent and let TypeScript light up a hundred errors. Don't. Add intent, keep color, and translate internally:

type ButtonProps = {
  /** @deprecated Use `intent` instead. `color` is removed in v3. */
  color?: 'green' | 'red' | 'gray';
  intent?: 'success' | 'danger' | 'neutral';
  children: React.ReactNode;
};

const colorToIntent = {
  green: 'success',
  red: 'danger',
  gray: 'neutral',
} as const;

export function Button({ color, intent, children }: ButtonProps) {
  // new prop wins; old prop still works via a mapping
  const resolved = intent ?? (color ? colorToIntent[color] : 'neutral');

  if (process.env.NODE_ENV !== 'production' && color && !intent) {
    console.warn(
      `Button: the \`color\` prop is deprecated. Use intent="${colorToIntent[color]}" instead.`,
    );
  }

  return <button className={intentClasses[resolved]}>{children}</button>;
}

Nobody's build breaks. Every existing color="green" keeps rendering exactly as before. New code uses intent. And critically, the component itself now knows the mapping from old to new — which is going to matter in about thirty seconds when we automate the migration.

A backward-compatible change buys you time, and time is the one thing a big-bang rewrite refuses to give you. Coexistence isn't a compromise. It's the whole plan.

Step two: deprecation is a message, not a delete

Marking something @deprecated is not the same as deleting it, and treating them as the same thing is why deprecations get ignored. A deprecation is a communication channel. Its entire job is to tell the next person who touches this code what to do instead — clearly, at the exact moment they'd otherwise reach for the old thing.

That JSDoc @deprecated tag isn't decorative. Editors strike through the prop and surface the message on hover, so a developer typing color= sees the replacement before they even hit save. The runtime warning catches the code that's already written. And if you want teeth, an ESLint rule turns "please stop" into "the build is yellow until you stop":

// eslint config — nudge, don't block yet
'no-restricted-syntax': [
  'warn',
  {
    selector: 'JSXAttribute[name.name="color"]',
    message: 'Button: the color prop is deprecated — use intent. Run the codemod: npx tsx scripts/button-color-to-intent.ts',
  },
],

The one rule I hold to: a deprecation must always name its replacement. "This is deprecated" with no path forward isn't a deprecation, it's nagging. Every warning I write ends with the exact thing to type instead, and ideally the command that'll do it for you. Which brings us to that command.

Step three: codemods move the boring changes for you

Here's where the hundred call sites stop being scary. If the change is mechanical — color="green" becomes intent="success", every time, no judgment required — then asking humans to do it a hundred times is both slow and a source of typos. A codemod is a script that rewrites source code by editing its syntax tree, and this is exactly what they're for.

// scripts/button-color-to-intent.ts — jscodeshift transform
import type { API, FileInfo } from 'jscodeshift';

const map: Record<string, string> = { green: 'success', red: 'danger', gray: 'neutral' };

export default function transform(file: FileInfo, api: API) {
  const j = api.jscodeshift;
  const root = j(file.source);

  root
    .find(j.JSXAttribute, { name: { name: 'color' } })
    // only touch color props on <Button>
    .filter((path) => {
      const el = path.parent.node;
      return el.name?.type === 'JSXIdentifier' && el.name.name === 'Button';
    })
    .forEach((path) => {
      const value = path.node.value;
      if (value?.type === 'Literal' && typeof value.value === 'string' && map[value.value]) {
        path.node.name.name = 'intent';
        value.value = map[value.value];
      }
    });

  return root.toSource();
}

Run it across the repo and every <Button color="green"> becomes <Button intent="success"> in one commit — a commit a reviewer can actually read, because the diff is uniform and mechanical. That's the real payoff: not just speed, but a reviewable migration instead of a hundred hand-edited files where any one of them could hide a mistake.

Codemods aren't always the answer, though, and I've watched people burn a day writing one for a change they could've done by hand in ten minutes. My test is two questions. Are there enough call sites that doing it manually is genuinely painful — dozens, not five? And is the transform mechanical, with no case where a human has to decide what the right replacement is? If either answer is no, skip the codemod. When the change needs judgment — "replace this prop, but only where the old behavior was actually intended" — a script can't make that call, and pretending it can just moves the bugs somewhere quieter.

When it can't be additive: version it side by side

Sometimes the new component isn't a tweaked version of the old one — it's a different thing that happens to share a name. A <DataTable> that moves from a props-driven column config to a headless row model isn't a new prop; it's a new mental model. You can't map the old API onto the new one, so coexistence-through-props doesn't work.

That's when you version at the module level instead of the prop level. Ship the new one alongside the old under its own name, and let call sites move when they're ready:

// old one keeps living, untouched, so nothing breaks
export { DataTable } from './data-table-legacy';
// new one ships next to it under a clear name
export { DataTableV2 } from './data-table-v2';

It's the same expand/migrate/contract shape, just one level up. Both exist. Features migrate to DataTableV2 on their own schedule, each migration a small reviewable change instead of a codebase-wide flip. When the last import of the legacy one is gone, you delete it. The name V2 is ugly on purpose — it's a temporary state that's supposed to disappear, and its ugliness is a standing reminder that the migration isn't finished. If DataTableV2 is still around in a year, that's a signal, not a feature.

Step four: contract — actually delete the old thing

This is the step everyone skips, and skipping it quietly undoes all the discipline that came before. Expand and migrate without contract just leaves you with two ways to do everything, forever, plus a warning nobody reads anymore. The deprecation was a promise to remove the old path. Contract is keeping it.

The good news is that after the additive change, the deprecation, and the codemod, contract is almost anticlimactic. You check that usage has actually hit zero — and you gate it, don't eyeball it:

# fails CI if a single old-style usage survives
grep -rn 'color=' src/ --include='*.tsx' && echo "still used — not safe to remove" && exit 1

When that returns nothing, you delete the color prop, the mapping, the warning, and the ESLint rule in one small commit. The component gets simpler — which is the tell that you did the whole thing right. A migration that ends with more code than it started with wasn't a migration, it was an accretion.

What this really changes

The thing I want to leave you with isn't the codemod or the deprecation tag — it's the reframing. Once you stop seeing "change a shared component" as one scary event and start seeing it as expand, migrate, contract, the fear mostly evaporates. Not because the work got smaller, but because every step is now individually safe and individually revertible. You're never one merge away from a broken build. You're always in a known-good state that happens to support two ways of doing something for a while.

And honestly, the willingness to make this move is a large part of what separates a component library people trust from one they're afraid of. A kit whose owners can evolve it safely keeps getting better. A kit whose owners are scared to touch it ossifies — every rough edge becomes permanent because fixing it feels too risky. The techniques here are what buy you the confidence to keep improving the thing everyone depends on.

Which raises the harder version of the same problem, and where I want to go next: it's one thing to evolve a component inside one repo where you can grep every call site. It's another to keep a shared UI kit in sync across several applications that each pull it in as a versioned package — where you can't see the call sites, can't run a codemod across them, and "just delete the old prop" can break an app you don't even have checked out. That's the next article.

If you've got a shared component you've been too scared to change, I'd genuinely like to hear what's holding it back — is it the call-site count, a missing safety net, or just that nobody's allowed to own it? Reach out and tell me which.

Here's a thing that took me too long to internalize: the most reusable UI code I've ever written renders nothing. No <div>, no class name, no markup at all. It just computes behavior and hands it to whoever called it. That sounds backwards — a UI component that produces no UI? — but it's the idea behind every component library that survived contact with more than one design system.

Compound components took us most of the way there: let the caller control structure while the component owns the coordination. But a compound component still ships markup. <Select.Option> renders a div, picks a class, decides on padding. The moment two products with different designs both want that select behavior, that markup becomes a fight. Headless components are the answer to "what if the component gave up the markup entirely and kept only the behavior."

The coupling nobody notices until it hurts

Think about what a <Combobox> actually does. It manages an open/closed state. It tracks the highlighted option. It handles arrow keys, Enter, Escape, typeahead. It wires up the ARIA attributes so screen readers announce it correctly. It filters options as you type. That's a lot of genuinely hard logic — the kind with edge cases you'll get wrong the first three times.

And then, almost as an afterthought, it renders some divs with some classes.

The hard part — the behavior — is completely universal. Every combobox everywhere needs the same keyboard handling and the same accessibility wiring. The easy part — the markup and styles — is completely specific. Your combobox looks nothing like mine. Yet a normal component welds those two together, so when I want your combobox's excellent keyboard handling but my design, I can't have it. I either fork your styles or reimplement your logic. Both are bad, and I've done both.

The behavior is universal. The markup is personal. A normal component fuses them and forces you to take both or neither.

Headless components unfuse them. They keep all the hard, universal behavior and give away zero markup, letting you supply the personal part yourself.

Three shapes of the same idea

"Headless" isn't one API. It's a family of three techniques that all separate behavior from rendering. They're worth knowing as a set, because you'll pick between them by feel.

Render props / children-as-a-function. The component computes state and calls your function to render. It decides nothing about looks.

<Toggle>
  {({ on, toggle }) => (
    <button onClick={toggle} className={on ? 'bg-[#22c55e]' : 'bg-gray-300'}>
      {on ? 'On' : 'Off'}
    </button>
  )}
</Toggle>

Toggle owns the on/off logic. You own every pixel. It renders literally nothing except by calling your function.

Hooks-as-API. The same idea, but the behavior is a hook instead of a component. This is the modern default, and honestly the cleanest — no wrapper component in the tree at all, just logic you call and props you spread.

function ColorSwatch() {
  const toggle = useToggle();
  return (
    <button
      onClick={toggle.toggle}
      aria-pressed={toggle.on}
      className={toggle.on ? 'bg-[#22c55e]' : 'bg-gray-300'}
    >
      {toggle.on ? 'On' : 'Off'}
    </button>
  );
}

Prop getters. For complex widgets, the hook hands you functions that return the props you need to spread onto your elements — including all the fiddly ARIA and event wiring you'd never remember to add yourself.

function Search() {
  const { getInputProps, getMenuProps, getItemProps, items, isOpen } = useCombobox({ items: options });
  return (
    <div>
      <input {...getInputProps()} />
      <ul {...getMenuProps()}>
        {isOpen && items.map((item, i) => (
          <li key={item.id} {...getItemProps({ item, index: i })}>{item.label}</li>
        ))}
      </ul>
    </div>
  );
}

You wrote the input, the ul, the li — your elements, your styles. But getInputProps() spread the ARIA roles, the keyboard handlers, the focus management onto them. You got the world-class behavior and kept total control of the markup. That's the whole promise in one code block, and it's why libraries like Downshift, React Aria, TanStack Table, and the Radix primitives are built exactly this way.

Why this is dependency injection wearing a costume

If this feels familiar, it should. Back in the composition and DI article I argued that a component should be handed its dependencies instead of reaching out to grab them. Headless components are that same principle turned inside out: instead of injecting data or services into a component, you're injecting the rendering into a behavior. The behavior doesn't reach out and decide how things look — you hand the looks in.

That's why the same benefits show up. A headless useCombobox is trivially testable, because you can drive its logic without rendering any particular UI. It's endlessly reusable, because it makes no assumption about markup. And it lets you change your mind about design without touching the logic, because the logic never knew what it looked like in the first place. Separation of concerns stops being a slogan and becomes a physical fact: the concern that's hard and universal lives in one place, the concern that's easy and specific lives in yours, and they meet through a thin, explicit interface.

The cost, honestly

I'm not going to pretend this is free, because the failure mode is real and I've watched teams walk into it. Headless components move work to the caller. When you use a styled <Button>, you get a button and you're done. When you use a headless toggle, you have to render the button, style it, and handle the states yourself. Multiply that across every component and a fully headless design system can feel like it gives you a pile of hooks and a homework assignment.

So the real-world answer is usually a layer cake, not a religion. Headless primitives at the bottom — the hard behavior, unstyled. A styled layer on top of them — your design system's actual <Button>, <Combobox>, <Select>, built once on the headless base and used everywhere. Most of your app imports the styled layer and never thinks about the headless one. The headless layer is there for the 10% of cases where the styled component doesn't fit and you need to drop down and rebuild the look while keeping the behavior. You get convenience by default and an escape hatch when you need it — instead of choosing between a rigid component library and reinventing keyboard navigation.

That layering is also the answer to the UI-kit-across-many-apps problem I've written about before: the behavior is shared once at the headless layer, and each app skins it without forking the logic. Same accessibility, same keyboard handling, different paint.

What I actually reach for

My rule of thumb is short. If a component's behavior is hard and its look varies — combobox, date picker, dropdown menu, data table, anything with keyboard and ARIA — I want it headless underneath, styled on top. If a component's look is fixed and its behavior is trivial, a plain styled component is right and headless is overkill. Most of a codebase is the second kind. But the handful of components that are the first kind are exactly the ones that cause the most pain when they're not headless, because they're the ones everyone needs slightly differently.

The mindset shift, though, is the real takeaway — the same one compound components started. You stop thinking "I'm building a combobox" and start thinking "I'm building combobox behavior, and the combobox is just one thing someone might render with it." Once you see UI logic as separable from UI markup, you can't unsee it, and you start noticing how much supposedly-reusable code isn't reusable at all — not because the logic is wrong, but because it's handcuffed to one specific set of divs.

That wraps the two most important component patterns — compose the structure, then hand off the behavior. Next in this run I want to get at the unglamorous half of building shared components: how you change one that dozens of places already depend on, without a giant risky rewrite — deprecation paths, codemods, and updating call sites without fear. If you've got a component library, go find the one component everyone reimplements slightly differently. That's almost always a behavior that should have been headless — tell me which one it is in yours.

You build a <Select>. It starts clean — options in, value out. Then the requests arrive. Someone needs a divider between groups. Someone needs an icon next to certain options. Someone needs a sticky "create new" row at the bottom. Someone needs a disabled option with a tooltip explaining why. Each request adds a prop: groups, renderIcon, footerSlot, disabledReason. Six months later your <Select> takes twenty-three props, half of them undocumented, and every new requirement means editing the component and praying you didn't break the other twenty-two use-cases.

This is the prop-explosion death spiral, and it happens to every successful shared component. The problem isn't that you added props badly. It's that props were the wrong tool for the job somewhere around request number three. What you actually needed was to stop configuring a component and start composing one. That's what compound components are.

The last few articles have been about boundaries and where code lives. This one starts a run on the patterns you build inside those boundaries — the techniques that decide whether the components you write get reused or quietly rewritten. Compound components are the first one because they're the most common thing people get wrong.

The wall you hit with props

Props are perfect right up until the caller needs control over structure. A boolean, a string, a callback — props handle those beautifully. But the moment the caller wants to decide what goes where — the order of things, what sits between them, what wraps them — props turn into a configuration language you're now forced to invent and maintain.

// the prop-explosion version — every layout decision is a prop
<Select
  options={options}
  value={value}
  onChange={setValue}
  renderOption={(o) => <Icon name={o.icon} />}
  groupBy="category"
  groupHeaderRenderer={(g) => <strong>{g}</strong>}
  footer={<CreateNewRow />}
  showDividers
  dividerAfter={[2, 5]}
/>

Look at that dividerAfter={[2, 5]}. That's the smell. You're passing array indices to describe where a line should appear, because the component owns the structure and the caller has to negotiate with it through props. Every new layout wish is a new prop, a new branch inside the component, and a new way for the component to break. The component knows too much about every caller, and every caller knows too much about the component's internal prop vocabulary.

When callers start passing you layout instructions as props, they're asking for composition. Give it to them.

Compound components invert the control

A compound component flips the relationship. Instead of one component that takes a pile of props describing structure, you expose a set of components that the caller arranges themselves. The classic shape everyone knows is the native <select>:

<select>
  <option>One</option>
  <optgroup label="More">
    <option>Two</option>
  </optgroup>
</select>

You don't pass <select> a groups prop. You compose <option> and <optgroup> inside it. The React version of that idea looks like this:

<Select value={value} onChange={setValue}>
  <Select.Option value="one">One</Select.Option>
  <Select.Divider />
  <Select.Group label="More">
    <Select.Option value="two" icon={<StarIcon />}>Two</Select.Option>
  </Select.Group>
  <Select.Footer><CreateNewRow /></Select.Footer>
</Select>

Every one of those twenty-three props just became a component the caller places wherever they want. Need a divider after the second item? Put a <Select.Divider /> there. Need an icon? Pass it to that one <Select.Option>. The component stopped owning the structure, and the caller took it back — which is exactly what they were trying to do with all those props. You didn't add flexibility by adding configuration. You added it by removing configuration and letting composition do the work.

The part that makes it actually work: shared state

Here's the question that trips people up: if <Select.Option> is a separate component sitting who-knows-how-deep inside the tree, how does clicking it tell <Select> about the new value? You can't pass props down — you don't own the JSX in between. The answer is React Context, and this is the one piece of machinery that turns a pile of dotted components into a real compound component.

const SelectContext = createContext<{
  value: string;
  onChange: (v: string) => void;
} | null>(null);

function Select({ value, onChange, children }: SelectProps) {
  return (
    <SelectContext.Provider value={{ value, onChange }}>
      <div role="listbox">{children}</div>
    </SelectContext.Provider>
  );
}

function Option({ value, icon, children }: OptionProps) {
  const ctx = useContext(SelectContext);
  if (!ctx) throw new Error('<Select.Option> must be used inside <Select>');
  const selected = ctx.value === value;
  return (
    <div
      role="option"
      aria-selected={selected}
      onClick={() => ctx.onChange(value)}
      className={selected ? 'bg-[#22c55e]/10' : ''}
    >
      {icon}
      {children}
    </div>
  );
}

// attach the children as properties — this is what enables the dot syntax
Select.Option = Option;
Select.Divider = () => <div role="separator" className="my-1 border-t border-gray-200" />;
Select.Group = Group;
Select.Footer = Footer;

The parent puts the shared state into context. Every child reads from context, so it doesn't matter how deeply it's nested or what the caller wraps it in — an <Option> three divs down still knows the current value and can report a click. That context is the invisible wire connecting components the caller arranged. Props flow explicitly to configure one option (its icon, its value); context flows implicitly to coordinate all of them. That division is the whole trick.

Notice the throw in Option. Because these components only make sense together, a compound component should fail loudly when used apart. A bare <Select.Option> with no <Select> around it is a bug, and catching it with a clear error is far kinder than letting it silently render nothing.

When it earns its place — and when it doesn't

Compound components are not free. They're more code, more indirection, and a context that has to exist. So I don't reach for them by default. I reach for them when three signals show up together.

The caller needs to control structure. If people keep asking to reorder parts, inject things between parts, or wrap parts — that's the tell. Structure control is what props are bad at and composition is good at.

The parts are meaningless alone but meaningful together. Tabs/TabList/Tab/TabPanel. Accordion/AccordionItem. Menu/MenuItem/MenuSeparator. None of those children make sense on their own, and all of them need to coordinate through shared state. That's the exact shape compound components fit.

There's real shared state to coordinate. If the children don't need to know about each other or a common value, you don't need the context, and you probably don't need this pattern — you just need components that accept children.

And when not to: a component with two or three stable props and no structural variation is perfect as a plain component. Wrapping a <Button> in a compound API is pure ceremony. The pattern earns its complexity only when the alternative is prop explosion. If you're not drowning in configuration props, you don't have the problem this solves.

The mental shift that matters

The reason I wanted to open the patterns run with this one is that compound components force a change in how you think, and that change outlasts the specific technique. The first time your component grows past a handful of props, you're not building a component anymore. You're designing an API that other people — including future you — will program against. And APIs are judged by how gracefully they handle the requests you didn't anticipate.

A prop-based component handles the unanticipated request by growing a new prop, and eventually collapses under its own configuration surface. A compound component handles it by letting the caller compose a solution you never had to predict — the divider you didn't plan for, the footer you didn't imagine — without you touching the component at all. That's the difference between a component people configure and a component people build with. The first one you maintain forever. The second one mostly maintains itself.

Next I want to push this one step further, to the pattern that takes the same idea and removes the last assumption a compound component still makes — that you own the markup at all. Headless components, render props, hooks-as-API: handing over behavior while giving up the UI entirely. If you've got a shared component in your codebase with more than a dozen props, go count them, then ask how many are really the caller trying to control structure. I'd bet the number is higher than you'd like — tell me what you find.

Somewhere around 2019, "container vs presentational components" got quietly filed under obsolete. Hooks had landed, the man who popularized the pattern had publicly walked it back, and every other blog post declared that containers/ and components/ folders were a relic. Move on, we have useEffect now.

That take was half right, and the half it got wrong is the interesting half. The folder convention deserved to die. The idea it was pointing at — separate the component that knows about the world from the component that just renders — didn't die at all. It went underground, changed shape, and quietly became one of the most useful instincts you can have. It's the exact split I kept landing on in the composition and DI article without naming it. Time to name it.

What the pattern actually said

For anyone who missed the original: the classic pattern split components into two kinds.

Container components knew how the app worked. They fetched data, held state, talked to the store, ran side effects — and rendered almost nothing themselves. Presentational components knew how things looked. They took props, rendered markup, fired callbacks, and knew nothing about where their data came from or where it went.

// the old shape — a container that fetches, and a dumb view it feeds
class UserListContainer extends React.Component {
  state = { users: [], loading: true };
  componentDidMount() {
    fetchUsers().then((users) => this.setState({ users, loading: false }));
  }
  render() {
    return <UserList users={this.state.users} loading={this.state.loading} />;
  }
}

function UserList({ users, loading }) {
  if (loading) return <Spinner />;
  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}

The value was real: UserList was trivial to test and reuse because it was just a function of its props, and the messy stateful part lived in one place. The problem was equally real: it was ceremony. Every stateful component needed a class wrapper around a function, entire files existed only to fetch-and-pass, and the two halves were welded together one-to-one anyway. You wrote twice the components for a separation that was mostly bookkeeping.

What hooks actually killed

Then hooks arrived, and here's the precise thing they changed: you no longer need a separate component to hold state or effects. The whole mechanical reason containers existed — "a function component can't have state, so wrap it in a class" — evaporated. A single function component can now fetch, hold state, run effects, and render:

function UserList() {
  const { data: users, isLoading } = useQuery(['users'], fetchUsers);
  if (isLoading) return <Spinner />;
  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}

One component. No container. And this is genuinely better for most cases — the ceremony is gone. So when people say "hooks killed container/presentational," this is what they mean, and they're right: hooks killed the requirement to physically split components just to have state.

But look closely at what they did not kill. UserList above now knows how to fetch. It reaches out and grabs its data — the exact reach-out anti-pattern from last time. It's convenient, and for a component you'll only ever use in one place, convenient is correct. The trouble is that people took "hooks removed the ceremony" and heard "the separation was pointless." Those are not the same sentence.

The idea that refused to die

Strip away the class wrappers and the folder names, and the pattern was never really about containers. It was about a boundary: one side knows about the outside world — data, state, side effects, where things come from and go — and the other side just takes inputs and renders. Hooks removed the boilerplate for drawing that boundary. They did not remove the reasons you'd want to.

You still want it every single time you need to:

• test rendering without a backend — a pure view takes props, no mock server required;
• reuse the same look with different data — the same table fed by a query, a websocket, or fixtures;
• show it in Storybook — a component that fetches its own data can't live in a story without a whole app around it;
• let a designer or a different feature reuse the visuals without inheriting your data layer.

So the modern move isn't containers/ folders. It's this: write the one-component version by default, and split along the data/render seam the moment you need the render half to stand on its own. Same UserList, split not because a rule said so but because you now have a reason:

// the "container" is just a function that fetches and delegates — no class, no folder
function UserListView({ users, isLoading }: { users: User[]; isLoading: boolean }) {
  if (isLoading) return <Spinner />;
  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}

function UserList() {
  const { data = [], isLoading } = useQuery(['users'], fetchUsers);
  return <UserListView users={data} isLoading={isLoading} />;
}

Notice there's no class, no containers/ directory, no naming ritual. Just a component that knows about the world wrapping a component that doesn't. The pattern survived; the ceremony didn't. That's the whole story of the "death" of container/presentational.

Where hooks made it fuzzier — and better

The honest update is that hooks also gave us a third option the old pattern didn't have, and it's often the best one: extract the world-knowledge into a custom hook instead of a component.

// the "container logic" is now a hook, not a wrapper component
function useUserList() {
  const { data = [], isLoading } = useQuery(['users'], fetchUsers);
  return { users: data, isLoading };
}

function UserList() {
  const { users, isLoading } = useUserList();
  if (isLoading) return <Spinner />;
  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}

Now the "smart" part is reusable on its own — any component can call useUserList — and the rendering stays simple. This is the container/presentational split turned sideways: instead of smart component + dumb component, it's smart hook + component that renders. For a lot of cases this is the sweet spot, because the reusable unit you actually wanted was the data logic, not a wrapper component. The boundary is still there. It just moved from a component seam to a hook seam.

So the real menu today isn't "container or not." It's three options, and you pick by what you need to reuse or isolate:

1. One component that does it all — the default, for anything single-use.
2. Smart hook + component — when the logic is what you want to reuse or test.
3. Fetching component + pure view — when the rendering is what you want to reuse, test, or hand to Storybook.

Server Components made the split matter again

Here's the twist nobody saw coming when they were busy declaring the pattern dead. React Server Components brought back a hard, physical version of exactly this boundary — and this time the framework enforces it.

A Server Component runs on the server, can be async, can hit the database directly, and ships no JavaScript to the browser. A Client Component ('use client') runs in the browser and is the only thing that can hold state or handle events. The natural, idiomatic shape is: Server Components fetch and compose the data; Client Components take that data as props and handle interactivity.

// app/users/page.tsx — Server Component: the "container", now literally server-side
export default async function UsersPage() {
  const users = await db.user.findMany();   // no client JS, runs on the server
  return <UserList users={users} />;
}

// UserList.tsx — 'use client': the interactive, presentational half
'use client';
export function UserList({ users }: { users: User[] }) {
  const [query, setQuery] = useState('');
  const shown = users.filter((u) => u.name.includes(query));
  return (/* search box + list */);
}

Read that and tell me it isn't container/presentational wearing a new uniform. The server component knows about the world — it fetches, it composes. The client component takes props and renders, plus handles the interactivity that has to live in the browser. The pattern everyone buried in 2019 is now baked into the newest thing React ships, except now the boundary isn't a convention you can ignore — it's a wall the runtime draws for you, and crossing it wrong is a build error.

What I actually believe about it

The pattern isn't dead and it isn't alive in its original form either. What happened is more useful: the rule dissolved and the instinct got sharper. I don't make containers/ folders. I don't wrap functions in classes. I don't split a component just because a style guide from 2016 says smart and dumb should be separate files.

What I do — every time — is keep one question live while I write a component: does this thing know about the world, or does it just render? When the answer is "both, and I need one of those halves on its own," I split along that seam, and I reach for whichever tool fits — a hook, a pure view, or a Server/Client boundary. The genius of the old pattern was never the folders. It was teaching a generation to notice that seam at all. That part was never obsolete. It just stopped needing a name to be worth doing.

That closes out this run on architecture and boundaries — where code lives, which way it depends, how to size and wire a component, and now where the smart/dumb line actually falls. Next I want to move from structure to patterns: the reusable-component techniques — compound components, headless UIs, behavior-as-API — that decide whether the things you build get used or quietly rewritten. If you've still got a containers/ folder in a codebase somewhere, don't rename it in a panic — just notice whether the split it's drawing is one you'd still draw today. Tell me what you find; I'd bet half of them are pulling their weight and half are pure ceremony.

Every code review eventually gets the comment: "this component is too big, split it up." It's good advice roughly half the time. The other half, someone dutifully chops a working 200-line component into eight files, and now understanding it means opening all eight, following props through four of them, and reassembling the whole thing in your head. The component wasn't fixed. It was smeared.

So "split it up" isn't the rule. Size is a symptom, not the disease. The real question underneath — the one the last three articles have been circling — is about dependencies: what does this component need to do its job, who gives it those things, and does the component go reach for them itself or get handed them? Get that right and the size mostly sorts itself out. Get it wrong and no amount of splitting helps.

Decomposition isn't about line count

Let me start with the part people get backwards. You don't split a component because it's long. You split it because it's doing more than one thing — because two different reasons to change are living in the same file.

Here's a component that's long but shouldn't be split:

function PolicyDetails({ policy }: { policy: Policy }) {
  // 180 lines of one coherent thing: rendering the details of a policy.
  // Header, status, coverage table, footer. All one job. All change
  // together, for the same reason ("we redesigned the policy view").
}

It's 180 lines and I'd leave it alone. There's one reason for it to change, and everything in it changes for that reason. Splitting it into <PolicyHeader>, <PolicyStatus>, <PolicyFooter> buys you nothing but four files to keep in sync — the classic mistake I wrote about in the smeared component. Now here's a component that's short but absolutely should be split:

function UserBadge({ userId }: { userId: string }) {
  const { data: user } = useQuery(['user', userId], () => fetchUser(userId));
  const theme = useContext(ThemeContext);
  const track = useAnalytics();

  useEffect(() => { track('badge_shown', { userId }); }, [userId]);

  if (!user) return <Spinner />;
  return <span style={{ color: theme.accent }}>{user.name}</span>;
}

Forty lines, and it's doing four unrelated jobs: fetching data, reading theme, firing analytics, and rendering. Four reasons to change, tangled together. This one I'd split — not because it's big, but because it's mixed.

That's the actual rule: decompose along reasons to change, not along line count. One component, one job, one reason to change. A long file doing one thing is fine. A short file doing four things is a problem waiting to surprise you.

The reach-out anti-pattern

Look again at UserBadge. The thing that makes it hard to reuse and impossible to test in isolation isn't its length. It's that it reaches out and grabs everything it needs from the ambient environment: it calls fetchUser directly, pulls theme from a context, grabs the analytics client from a hook. It's wired straight into the world.

This is the component equivalent of an arrow pointing the wrong way — the exact problem from the dependency-direction article, now one level down, inside a single component. UserBadge claims to be a small presentational thing, but it depends on your data layer, your theme system, and your analytics pipeline. Drop it into a Storybook story or a test and it explodes, because it demands a whole app around it just to render a name.

You feel this the moment you try to reuse it. "I just want to show a user's name in a different color" — but you can't, because the color is hard-wired to ThemeContext.accent, and the name is hard-wired to this query. The component grabs its dependencies instead of accepting them, so it only works in the one spot it was born in.

Hand it over instead

The fix is old and boring and it's called dependency injection, which sounds like a Java framework and is actually just this: don't let a component fetch its own dependencies — hand them in. On the frontend, "inject" mostly means "pass as a prop" or "provide through context," and the entire idea is that the component stops knowing where things come from.

// UserBadge now just renders. It's handed everything it needs.
function UserBadge({ name, color }: { name: string; color: string }) {
  return <span style={{ color }}>{name}</span>;
}

That's it. It doesn't fetch, doesn't read context, doesn't track. It takes a name and a color and renders. Now it works in a test with two strings, works in Storybook with no providers, works anywhere. The fetching, theming, and analytics didn't disappear — they moved up to a component whose job is exactly that wiring:

function ConnectedUserBadge({ userId }: { userId: string }) {
  const { data: user } = useQuery(['user', userId], () => fetchUser(userId));
  const theme = useContext(ThemeContext);
  const track = useAnalytics();

  useEffect(() => { track('badge_shown', { userId }); }, [userId, track]);

  if (!user) return <Spinner />;
  return <UserBadge name={user.name} color={theme.accent} />;
}

We split UserBadge — but notice how we split it. Not into "the top half and the bottom half." Along a dependency seam: one component that knows about the outside world (fetching, context, side effects), and one that knows nothing and just renders what it's given. That seam is the useful cut. The line-count cut isn't.

Injection is a spectrum, not a switch

You don't have to reach for a DI container or some ceremony. Frontend dependency injection is mostly choosing, per dependency, how far to push it out of the component. From least to most flexible:

Hard-coded (no injection). The component imports and calls the thing directly. Fine for genuinely stable, app-agnostic dependencies — a component importing clsx or a pure formatDate doesn't need those injected. Not everything is a dependency worth managing.

Props. The default and the one you'll use most. Pass the value, the callback, the data. Explicit, type-checked, trivially testable. If you're not sure how to inject something, pass it as a prop and stop overthinking it.

// the data source is injected — the list doesn't know or care where rows come from
function DataTable<T>({ rows, onRowClick }: { rows: T[]; onRowClick: (row: T) => void }) { /* ... */ }

Context. For dependencies that are truly cross-cutting and tedious to thread — theme, current user, a query client, an analytics sink. Context is injection at a distance: the component pulls from context, but what's in that context is decided at the provider, so tests and stories can hand it a fake. The danger is overusing it — every context dependency is an invisible input that doesn't show up in the props, and a component that reads six contexts is just as wired-in as one that imports six modules. Use context for the few things that are genuinely app-wide, and props for everything else.

Render props / children as a function / slots. Inject behavior or markup, not just values. This is how you build something reusable without it knowing what it renders — a <List> that takes a renderItem, a <Form> that takes children. It's dependency injection where the dependency is a piece of UI.

The skill isn't picking one. It's matching each dependency to the lightest mechanism that still lets you swap it when you need to. Most things: props. A few app-wide things: context. Behavior you want to vary: a function. Genuinely fixed, generic utilities: just import them.

The payoff you actually feel

This all sounds abstract until the day it isn't. Three moments where injecting dependencies instead of grabbing them pays for itself:

Testing. A component handed its dependencies is a component you test with plain values — no mocking the fetch layer, no wrapping in five providers, no fighting the framework. render(<UserBadge name="Ada" color="#22c55e" />) and you're done. The reach-out version needs a mock server and a provider tree just to assert on a name.

Reuse. The whole reason the "small" UserBadge couldn't be reused was that it grabbed its color from one specific context. Hand the color in and it drops into any screen, any theme, any story. Injected dependencies are what make a component portable — which, not coincidentally, is the same portability promise that decides whether something belongs in shared/ at all.

Changing your mind. Swap fetchUser for a different endpoint, replace the analytics provider, feed the table rows from a websocket instead of a query — and the leaf components don't change at all, because they never knew where their data came from. You only touch the wiring layer. The thing you were afraid to change turns out to have one owner, in one place.

The rule I actually carry around

I've stopped asking "is this component too big." It's the wrong question and it leads to smearing. The questions I ask instead are two: how many reasons does this component have to change (that tells me whether to split, and where), and does it reach for its dependencies or get handed them (that tells me whether it'll be testable and reusable, or welded to one spot).

Composition, in the end, isn't about making things small. It's about making the seams fall in the right places — cutting along dependencies, not along line counts — and being deliberate about which component owns the wiring and which just renders what it's told. Do that and your big components stay big and fine, your small ones stay focused, and the word "reusable" starts meaning something instead of being a hope you wrote in a PR description.

Next I want to take this exact idea — the split between "knows about the world" and "just renders" — and hold it up against the pattern that's been arguing about it for a decade: container versus presentational components, and whether that split still makes sense now that we have hooks and Server Components. If you've got a component you're scared to reuse, look at what it reaches for instead of what it's handed. That list is usually the whole reason — tell me what's on yours.

Draw your app's architecture on a whiteboard and it always looks clean. Neat boxes, sensible names, tidy layers stacked top to bottom. Everyone nods. Then you open the code and it doesn't match the drawing at all — a UI component reaches into a data-fetching file, a "shared" helper imports a specific feature, two features import each other through a back door nobody remembers adding.

The whiteboard is the architecture you wish you had. The import statements are the architecture you actually have. And the gap between them is where most large React apps quietly rot.

I've spent the last two articles on where code lives — the shared/ folder and barrel files. This one is about the thing underneath both: not where a module sits, but which way it points. Who is allowed to import whom. Because that — the direction of the arrows — is the real shape of your app.

Your folders lie, your imports don't

Here's the uncomfortable part. Folder structure is a suggestion. You can put a file in shared/ and it means nothing about how coupled it is — what matters is what it imports and who imports it. Two apps with identical folder trees can have completely different architectures, because architecture isn't the tree. It's the graph.

Every import statement is a directed edge: "this module depends on that one." Collect all of them and you get your dependency graph — the one true map of your app. And that map answers the questions folders can't:

• If I change this file, what breaks? (everything that points at it)
• Can I delete this feature cleanly? (only if nothing outside points into it)
• Why is this "small" component impossible to reuse? (because it points at half the app)
• Why did one route pull in the entire bundle? (follow the arrows — you'll find a bad one)

You already met that last one in the barrel article. That wasn't really a barrel problem. It was an arrow problem — an import pointing somewhere it shouldn't, and a barrel making it easy.

Folders describe intent. Imports describe reality. When they disagree, reality wins.

Arrows have a correct direction

The single most useful architectural rule I know fits in one sentence: dependencies should point in one direction — from specific to general, from volatile to stable, never back.

Think of your app in rough layers, top to bottom:

app          ← wires everything together
features     ← "edit policy", "create claim" — business use-cases
entities     ← domain models: Policy, Claim, User
shared       ← generic, app-agnostic: Button, formatDate, http client

The rule is simple: arrows only ever point down. A feature may import an entity. An entity may import from shared. shared imports nothing from above it — not an entity, definitely not a feature.

Why down and not up? Because the lower you go, the more stable and general the code is. shared/Button doesn't know your app sells insurance. entities/Policy knows about policies but not about the specific "renew a lapsed policy" screen. The edit-policy feature knows the most and changes the most. If a stable module (Button) points up at a volatile one (edit-policy), then every time that feature changes, your generic button is at risk — and it's no longer generic. You just welded the most reusable thing in your app to the least reusable one.

The moment shared imports a feature, the word "shared" becomes a lie. This is the mechanical reason the shared/ folder turns into a junk drawer: not because people are messy, but because they let arrows point the wrong way, and an upward arrow is exactly how a generic folder gets chained to a specific feature.

The two arrows that kill you

There are two directions of arrow that do almost all the damage. Learn to see them and you've caught 90% of architectural decay.

The upward arrow — general depending on specific. A shared utility importing a feature. An entity importing a screen. A design-system component importing app-specific business logic. Every one of these takes something that was supposed to be reusable and staples it to something that isn't.

// shared/lib/format.ts  — a "generic" formatter
import { POLICY_STATUS_LABELS } from '@/features/edit-policy/constants';
//                                    ^^^^^^^^^^^^^^^^^^^^^^ upward arrow

export function formatStatus(code: string) {
  return POLICY_STATUS_LABELS[code] ?? code;
}

This looks harmless. It compiles, it works, the PR gets approved. But shared/lib/format now depends on edit-policy. Import that formatter anywhere — a totally unrelated screen — and you've dragged edit-policy in with it. "Shared" now means "shares a dependency on one specific feature." The fix is to push the specific thing up to where it belongs and keep the shared thing ignorant:

// shared/lib/format.ts — knows nothing about policies
export function formatStatus(code: string, labels: Record<string, string>) {
  return labels[code] ?? code;
}

// features/edit-policy/... — the feature owns its own labels
formatStatus(policy.status, POLICY_STATUS_LABELS);

The generic module stayed generic. The specific knowledge stayed in the feature. The arrow points down again.

The sideways arrow — feature importing feature. edit-policy reaches directly into billing-dashboard. Now you can't touch one without understanding the other, you can't delete either cleanly, and if billing-dashboard also imports edit-policy back, you've got a cycle — two modules that can only be understood as one tangled unit. Cross-feature imports are how a codebase where every feature was supposed to be independent becomes one where nothing is.

The fix isn't "never let features talk." It's how they talk. Pull the shared concept down into an entity both can depend on, or lift the coordination up into the app layer that's allowed to know about both. Features don't import each other sideways; they meet in a layer above or below. Arrows down, never across.

A feature's public API is the only door in

Here's what makes the "arrows down" rule enforceable instead of a vibe: each feature exposes one public entry point, and nobody imports past it.

features/edit-policy/
  index.ts            ← the ONLY thing outsiders may import
  ui/EditPolicyForm.tsx
  model/useEditPolicy.ts
  model/validation.ts   ← private
  lib/mapPolicyDto.ts   ← private

// features/edit-policy/index.ts — deliberate public surface
export { EditPolicyForm } from './ui/EditPolicyForm';
export { useEditPolicy } from './model/useEditPolicy';
// validation, DTO mapping, internal helpers stay private

Anything outside the feature imports from @/features/edit-policy and nothing deeper. The insides — validation rules, DTO mapping, private hooks — are free to change, because from the outside they don't exist. This is the good use of a barrel I argued for last time: not to shorten imports, but to draw a wall with exactly one door in it.

Reach past that door — import { validatePolicy } from '@/features/edit-policy/model/validation' — and you've done two bad things at once: coupled to an internal that was never promised to stay, and created an arrow that no longer respects the feature's boundary. The public API is what turns "arrows point down" from a hope into a checkable rule. There's a door. You use the door.

Make the graph impossible to get wrong

You will not hold this in your head. Nobody does. On a real team, someone adds an upward import at 6pm on a Friday, it works, it ships, and the arrow is now part of your architecture forever. Good intentions don't scan the dependency graph. Tooling does.

I let a linter own the rule. eslint-plugin-import with no-restricted-imports, or a boundaries plugin (eslint-plugin-boundaries, or the import rules in Biome), encoding the layer directions as actual errors:

// eslint — shared may not import upward, features may not import each other
'no-restricted-imports': ['error', {
  patterns: [
    { group: ['@/features/*', '@/entities/*'], message:
      'shared/ must not import from features or entities — arrows point down only.' },
  ],
}],

Now the wrong arrow doesn't get a code review debate. It gets a red squiggle before the commit. The architecture stops being a document people forget and becomes a constraint the tooling enforces. That's the whole game: an architectural rule that isn't mechanically enforced is a rule that's already being broken somewhere you haven't looked.

And once the arrows are constrained, a dependency-graph visualiser (madge, dependency-cruiser, or your bundler's analyzer) stops being a curiosity and becomes a health check. Run madge --circular and it lists your cycles — every one a place where two modules secretly became one. A clean graph with arrows all pointing down is not an aesthetic preference. It's the difference between a change that touches one file and a change that touches forty.

Why this is the article under the others

The shared/ folder turns into a junk drawer because people let it depend upward. Barrel files blow up your bundle because they make a bad arrow cheap to draw. Features become impossible to delete because they point sideways at each other. Every one of those is the same disease wearing a different symptom: an arrow going the wrong way.

So when I evaluate an architecture now, I don't start with the folder tree — that's the story the code tells about itself. I start with the graph: pull the imports, look at the direction of the arrows, and find the ones pointing up or sideways. Those arrows are the whole diagnosis. Fix them and the folders mostly sort themselves out. Ignore them and you can reorganize folders every quarter and still be stuck in the same tangle, because you were rearranging the boxes while the arrows — the thing that actually mattered — stayed exactly where they were.

Next I want to turn from where the arrows point to how big the boxes should be — composition versus decomposition, and how to hand a component its dependencies instead of letting it reach out and grab them. If you want a fast, slightly alarming read on your own app tonight, run madge --circular src and count the cycles. Tell me the number — I'm curious whether you're prouder or more horrified than you expected.

There's a specific kind of import that feels like good engineering:

import { Button, Card, Modal, Tooltip } from '@/shared/ui';

One line. One path. Clean. Compare it to the honest version:

import { Button } from '@/shared/ui/Button';
import { Card } from '@/shared/ui/Card';
import { Modal } from '@/shared/ui/Modal';
import { Tooltip } from '@/shared/ui/Tooltip';

The first one looks like a tidy public API. The second looks like clutter. So of course teams reach for the first — they add an index.ts that re-exports everything, and the whole folder gets a single front door. That file is a barrel, and it's one of the most quietly expensive habits in a React codebase. Not because it's wrong. Because it's right just often enough that people stop questioning it.

I brought this up at the end of the shared/ article and promised to come back to it. Here's the come-back.

What a barrel actually is

A barrel is just a file — almost always index.ts — whose only job is to re-export other modules:

// shared/ui/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
export { Tooltip } from './Tooltip';

Now @/shared/ui resolves to this file, and consumers import named things from one place. The appeal is real: imports get shorter, the folder gets a defined surface, and you can move Button.tsx around internally without breaking any consumer, as long as the barrel keeps pointing at the right place. That last part — decoupling the internal file layout from the public import path — is a genuine architectural benefit, not just cosmetics. It's the same "public API of a folder" idea that makes feature boundaries work.

So far this sounds like something you'd want everywhere. That's exactly the trap.

The cost hides where you're not looking

Here's the problem. When you write import { Button } from '@/shared/ui', you are not importing Button. You are importing the barrel, and the barrel imports everything. Button, Card, Modal, Tooltip, and whatever those pull in — the whole folder loads to hand you one component.

"But tree-shaking removes the unused ones," you say. Sometimes. Tree-shaking is real, but it's fragile, and a barrel is exactly the shape that breaks it. All it takes is one module in the barrel with a side effect — a file that runs code at import time, registers something, mutates a global, or is marked as having side effects in package.json — and the bundler can no longer prove the other exports are safe to drop. To stay correct, it keeps them. Your one-line Button import just pulled in Modal, its focus-trap library, and the animation dependency Tooltip uses.

You won't see it in code review. The import line looks identical whether the tree shakes cleanly or not. You'll see it in a bundle analyzer six months later, staring at a route that weighs 400KB and wondering why a page with two buttons is importing a charting library. The answer is almost always a barrel somewhere in the chain, quietly gluing unrelated things together.

There's a second cost that shows up sooner: build and dev-server speed. Every barrel is a fan-out. Import one thing through @/shared/ui and the module graph has to resolve every file the barrel touches, and every file those touch. In a big app with barrels re-exporting barrels re-exporting barrels, you get a dependency graph that explodes on almost any import. Cold dev starts crawl. Hot updates touch more than they should. The tooling spends its time walking a graph you created for the sake of a shorter import line.

A barrel trades a real cost you can't see for a cosmetic benefit you can.

The worst offender: the app-wide barrel

The pattern that does the most damage is the ambition to have one barrel at a high level that re-exports a whole layer:

// features/index.ts — please don't
export * from './edit-policy';
export * from './create-claim';
export * from './billing-dashboard';
export * from './user-settings';
// ...twenty more

Now import { EditPolicyForm } from '@/features' reaches into a barrel that transitively imports every feature in the app. Import one feature and you've referenced all of them. Code-splitting — the entire point of which is that a route loads only what it needs — quietly stops working, because from the bundler's view everything is connected to everything through this one file. I've watched a lazy-loaded route pull in the whole app because a single import went through a top-level barrel instead of reaching for the specific module.

The export * form is especially nasty. It's not just eager; it forces the bundler to load a module just to find out what names it exports, so it can figure out which star-export a given name came from. Named re-exports (export { X } from './x') are at least explicit. export * is a blank check.

When a barrel earns its place

I'm not anti-barrel. I use them. The question is never "barrels: yes or no." It's "does this specific barrel pay for itself." A barrel earns its place when three things are true at once.

It wraps a genuine, stable public API. A design-system package where Button, Card, and Modal are the whole point and consumers legitimately pull from across it — that's a real interface, and a barrel is the right way to express it. The barrel isn't hiding a mess; it's naming a surface that was always meant to be used as a whole.

It's small and internally cohesive. A barrel over five related components in one feature is cheap — importing one probably means you're near the others anyway, and the fan-out is tiny. The cost of a barrel scales with what's behind it. Small folder, small cost.

Nothing behind it has surprising weight or side effects. Pure, light modules tree-shake fine through a barrel. The danger is heavy or effectful modules — a component that drags in a 200KB dependency, a file that runs setup at import. One of those behind a barrel poisons every import that passes through it.

Miss any of those and the barrel is working against you. A top-level @/features barrel fails all three: not a stable surface, not small, and full of heavy things. A shared/ui/index.ts over a real design system passes all three. Same mechanism, opposite verdict — which is the whole reason "always use barrels" and "never use barrels" are both wrong.

What I actually do

My rules are boring, which is how I like architecture rules.

Import from the specific file by default. import { Button } from '@/shared/ui/Button' is my normal. The import is three words longer and I never think about it again. No fan-out, no tree-shaking gamble, no accidental coupling.

// default: reach for the exact thing
import { Button } from '@/shared/ui/Button';
import { formatCurrency } from '@/shared/lib/money';

Add a barrel only at a real boundary I've decided to publish. A feature's public entry point, a design-system package's root — places where "this is the surface, use it as one" is a deliberate architectural statement, not a convenience. And when I do, I write explicit named re-exports, never export *:

// features/edit-policy/index.ts — a deliberate public surface
export { EditPolicyForm } from './ui/EditPolicyForm';
export { useEditPolicy } from './model/useEditPolicy';
// internal helpers are NOT re-exported — they stay private

That barrel is doing architectural work: it defines what the feature exposes and hides everything else, so the rest of the app can't reach into the feature's guts. That's a barrel as an encapsulation boundary, which is worth having. A barrel as a typing convenience usually isn't.

Never barrel a whole layer. No @/features, no @/entities mega-barrel. Layers are not modules; they're categories. Giving a category a single import door is how code-splitting dies.

Verify with the analyzer, not with faith. Tree-shaking is a claim, not a guarantee. Run a bundle analyzer, find the route that's too heavy, and trace it. More often than not the culprit is a barrel doing exactly what I described — and the fix is changing one import from the barrel to the specific file.

The real lesson isn't about barrels

Strip away the mechanics and this is the same idea as the shared/ article, pointed at a different symptom. A barrel is a public API for a folder. Public APIs are worth having when there's a real boundary to protect and a real surface to name. They're pure cost when you add them out of habit, to make imports prettier, over a pile of things that were never meant to be used as a unit.

So the question to ask isn't "should this folder have an index.ts." It's "does this folder have a public API worth defining — and am I willing to pay the fan-out to define it." When the answer is yes, barrel it, name the surface, and hide the rest. When the answer is "I just want shorter imports," reach for the specific file and move on. The prettier import was never worth the bundle you couldn't see.

Next in this stretch on architecture, I want to get at the thing underneath both of these articles: how modules should depend on each other at all — the direction of the arrows, who's allowed to import whom, and why a dependency graph is the most honest picture of your app's health. If you've got a bundle that mysteriously balloons on one route, open the analyzer and go hunting for a barrel — then tell me what you found. I'm always curious how far the fan-out reached.

Open the shared/ folder in almost any React app that's been alive for a year. Count the files. Then try to explain, out loud, what the folder is for — not what's in it, what it's for. You'll stall. There's a date formatter, sure, and a Button. But there's also useUserPermissions, a formatPolicyNumber, half a checkout state machine, a legacyApiAdapter, and three hooks whose names start with use and end in a shrug.

That folder didn't get that way because someone was careless. It got that way because shared/ is the one folder in your app with no rule attached to it. Everything else has a reason to reject a file. shared/ accepts everything. And a folder that accepts everything isn't a category — it's a drain.

I already flagged this in the code structure article: shared/ is the most abused folder in React architecture. That piece told you the rule. This one is about why the rule is so hard to keep, and how to dig out once you've already lost.

Why the drawer fills up

The junk drawer isn't a discipline problem. If it were, telling people "be more careful about shared/" would fix it. It never does. The rot is structural, and it comes from three forces that all push the same direction.

The naming trap. You write a hook. Where does it go? If it has an obvious owner — features/edit-policy — the answer is easy. But a lot of code sits in the awkward middle: not clearly owned, not clearly generic. useDebouncedValue is generic. usePolicyDraftAutosave is owned. But useAutosave, the one that started generic and quietly grew a policyId parameter — that one has no obvious home. So it goes to shared/, because shared/ never says no.

The reuse reflex. The moment a second file wants something, the instinct is to "lift it up" so both can reach it. This feels like good engineering. It's usually premature. Two components in the same feature using one helper is not a reason to move that helper three layers up into shared/lib — it's a reason to keep it inside the feature. Reuse across a boundary is a real signal. Reuse within a boundary is just normal code living near the thing that uses it.

The path of least resistance. shared/ is at the bottom of the dependency graph, so everything can import from it. That makes it the safest place to drop something when you're in a hurry and don't want to think about ownership. No import will ever break. And that's exactly the problem: the folder that's safe to import from is also the folder that's frictionless to dump into.

Put those three together and you don't get a junk drawer because people are bad at their jobs. You get one because the folder is doing precisely what an unconstrained folder does under pressure. Delivery pressure always wins over categorization, and shared/ is where "I'll sort it later" goes to never be sorted.

shared/ is not a place you put things. It's a promise you make about them.

That reframing is the whole article. The promise is: this code is domain-agnostic and portable — it would make sense in a completely different product. Every file in shared/ is you signing that promise. The drawer fills up because people put things there without noticing they're signing anything.

The test that actually works

The rule I gave in the structure article still holds, and it's the only test I've found that survives contact with a real team:

A file belongs in shared/ only if you could move it to a different product at the same company and it would still make sense.

A Button? Moves fine. A formatCurrency? Moves fine. An http client with your auth interceptor? Borderline — it moves if the auth scheme is company-wide, stays if it's app-specific. A useUserPermissions hook that knows your permission strings? Doesn't move. It's dressed up as generic — it takes a permission key, it returns a boolean, it looks reusable — but it's welded to your domain's idea of what a permission is. That's not shared code. That's domain code wearing a generic costume.

Here's the tell, in code. This looks shared:

// shared/hooks/usePermission.ts
export function usePermission(key: string): boolean {
  const { permissions } = useCurrentUser();
  return permissions.includes(key);
}

It isn't. useCurrentUser is a domain concept. The moment this hook reaches sideways into entities/user, it stopped being portable — it now depends on your app's notion of a user. Move it to a different product and it breaks. It belongs in entities/user, exported as part of that entity's public surface. What's left in shared/ should be the genuinely dumb primitive:

// shared/lib/includes.ts — portable, knows nothing
export const hasKey = (keys: string[], key: string) => keys.includes(key);

The portability test isn't about whether code can be reused. Almost anything can be reused if you squint. It's about whether the code knows about your domain. Knowledge is the boundary, not usage.

Make the boundary a wall, not a suggestion

A rule that lives only in a code review is a rule you will lose. Reviewers get tired. New people don't know it. The pressure that fills the drawer doesn't take weekends off. So the direction of dependencies — lower layers never importing from higher ones — has to be enforced by tooling, not vigilance.

ESLint's no-restricted-imports gets you most of the way with zero extra dependencies:

// eslint.config.js
export default [
  {
    files: ['src/shared/**'],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          patterns: [
            {
              group: [
                '@/features/*',
                '@/entities/*',
                '@/widgets/*',
                '@/pages/*',
                '@/app/*',
              ],
              message:
                'shared/ must not import from higher layers. If this file needs domain code, it does not belong in shared/.',
            },
          ],
        },
      ],
    },
  },
];

Now the usePermission example from earlier fails the build the instant it imports useCurrentUser. The error message isn't just "no" — it explains the promise: if this file needs domain code, it doesn't belong here. The lint rule becomes the reviewer who never gets tired and never forgets the rule. For richer needs — enforcing that features can't import each other, that entities stay isolated — a dedicated boundaries plugin does the same job with more expressive rules, but the built-in gets a small team surprisingly far.

The point isn't the exact config. It's that the promise stops depending on everyone remembering it. You made shared/ say no. That single change is the difference between a folder that stays small and one that quietly triples every quarter.

Digging out of one you already have

Prevention is easy to talk about when the drawer is empty. Most of the time it isn't. You've inherited forty files and a folder that's load-bearing in ways nobody documented. You can't stop shipping features to go on an architecture retreat, and a big-bang "fix shared/" pull request is a merge-conflict machine that reviewers will rubber-stamp out of exhaustion. So don't do that. Dig out incrementally.

First, audit without moving anything. Go through shared/ file by file and tag each one with a comment — three buckets only:

• Portable — passes the test. Leave it. This is what shared/ is for, and seeing what legitimately qualifies is calming.
• Owned — knows about a domain concept. It has a real home in an entity or a feature; it's just sitting in the wrong place.
• Split — genuinely two things fused together: a portable core with a domain-specific wrapper grown around it. The useAutosave-that-grew-a-policyId case.

Then move the easy ones. The Owned bucket is pure relocation — cut the file, paste it into its real home, fix the imports, done. Your lint rule from the previous section will actually help here: as you move domain code out, anything still illegally reaching into higher layers lights up red, showing you the next thing to fix. The compiler turns into a to-do list.

Then split the hard ones. For each Split file, separate the portable core from the domain wrapper. The core stays in shared/ as a dumb primitive. The wrapper moves down to the feature that needs the domain-specific behavior:

// before — one file in shared/, quietly domain-aware
// shared/hooks/useAutosave.ts
export function useAutosave(policyId: string, draft: PolicyDraft) { /* ... */ }

// after — the portable half
// shared/lib/useAutosave.ts — generic, no domain knowledge
export function useAutosave<T>(key: string, value: T, save: (v: T) => Promise<void>) { /* ... */ }

// after — the domain half, where it belongs
// features/edit-policy/model/usePolicyAutosave.ts
export function usePolicyAutosave(policyId: string, draft: PolicyDraft) {
  return useAutosave(`policy:${policyId}`, draft, savePolicyDraft);
}

Notice the generic useAutosave got better by being forced portable — it now takes its save function as an argument instead of hard-coding savePolicyDraft, which makes it genuinely reusable for the first time. Enforcing the boundary didn't just tidy the folder. It improved the primitive.

Then delete. The satisfying part. Once the Owned and Split files are gone, you'll almost always find a handful of files nothing imports anymore — helpers that existed only to serve code that moved. Delete them. A shrinking shared/ is the clearest signal the dig-out is working.

You don't have to finish in one sitting. Do a bucket a week. The direction matters more than the speed: as long as shared/ is getting smaller and more portable over time instead of larger and vaguer, you're winning.

A word on the barrel

While you're in here, you'll be tempted to add an index.ts that re-exports everything so imports look clean: import { Button, formatCurrency } from '@/shared'. Resist making that reflexive. A barrel over a genuinely small, stable, portable shared/ is fine. A barrel over the junk drawer just gives the junk drawer a tidy front door — and it can quietly drag your whole shared/ tree into every bundle that touches one export. The clean import is cosmetic; the coupling underneath is real. Fix the contents first. The public API of a folder is only worth having once the folder actually keeps a promise. That trade-off — barrels, bundles, and what a folder's public surface should really be — is a whole topic on its own, and one I want to come back to.

The folder was never the problem

It's easy to read all this as "shared/ is bad, avoid it." That's the wrong lesson. Every non-trivial app needs a home for genuinely portable code, and shared/ is a perfectly good name for it. The folder was never the enemy.

The missing promise was. A junk drawer is just a drawer that nobody agreed on the contents of. The fix isn't a better folder name or a stricter reviewer — it's making the promise explicit, and then making a machine enforce it so the promise survives the next deadline. Do that, and shared/ stops being the place your architecture goes to die and goes back to being the boring, dependable bottom of the stack. Boring is the goal. In shared/, boring is the whole point.

Next, I want to pick up the barrel thread I brushed past earlier: why the tidy index.ts that gives a folder a clean front door can quietly drag half your app into a bundle that only needed one function — and when it's still worth it.

If you've got a shared/ folder you're a little afraid to open — or a war story about one that got completely out of hand — I'd genuinely like to hear it. Reach out; I collect these.

The first time someone tells you that you can build a 3D scene — a rotating model, a lit environment, a VR world — using React, it sounds like a category error. React is for interfaces. Buttons, forms, lists. Three-dimensional graphics are a different universe with their own math, their own pipeline, their own everything. Surely gluing them together is a hack.

It isn't, and the reason it isn't is the perfect note to end this series on. Because after twenty-nine articles about data fetching and forms and auth and desktop and mobile, the thing rendering React in 3D quietly proves is the idea that was underneath all of it the whole time: React was never really about the DOM. React is a system for describing a UI as a function of state and letting a renderer figure out how to make it real. The DOM was just the first and most common target. Point that same system at a 3D scene graph and it works — not as a trick, but because 3D was always within the reach of what React actually is.

So this last article is short, and it's really about a realization more than a technology. Let me show you what I mean.

The Scene Graph Is Just Another Tree

Here's the conceptual key. React renders trees. The DOM is a tree of elements — a div containing a span containing text. A 3D scene is also a tree: a scene contains a mesh, a mesh has a geometry and a material, lights and cameras sit alongside them. Same fundamental shape — a nested hierarchy of things — which means React's component model, built for exactly that shape, fits a 3D scene as naturally as it fits a webpage.

React Three Fiber is the renderer that makes this literal. It's React — real React, same hooks, same state, same composition — where the elements are 3D objects instead of HTML tags. You don't write <div>; you write <mesh>. You don't nest <p> inside <section>; you nest a geometry and a material inside a mesh.

import { Canvas } from '@react-three/fiber';

function Box() {
  return (
    <mesh rotation={[0.4, 0.2, 0]}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="#22c55e" />
    </mesh>
  );
}

export function Scene() {
  return (
    <Canvas>
      <ambientLight />
      <pointLight position={[10, 10, 10]} />
      <Box />
    </Canvas>
  );
}

Read that and the uncanny thing is how ordinary it is. It's components. <Box /> is a component you could reuse, wrap in a list, conditionally render. rotation and color are just props — drive them from state and the cube animates or recolors, because it's the same reactivity you've used all series. <mesh> is to a 3D renderer what <div> is to the DOM renderer: a primitive the renderer knows how to draw. Everything you know about composing React components — props down, state-driven rendering, reuse, hooks — applies unchanged. Only the primitives at the bottom of the tree are different.

VR and AR Are Just More of the Same Realization

Once you accept that React can describe a 3D scene, VR and AR stop being a separate leap. A VR headset is, from the code's point of view, a 3D scene rendered in stereo with head tracking. AR is a 3D scene composited over a camera feed. The scene — the tree of meshes and lights and cameras — is the same tree React Three Fiber already renders; the WebXR layer adds the headset and the tracking on top.

So the progression is one idea extended, not three separate technologies to learn. Describe a 3D scene as a React tree. Render that tree to a screen — that's 3D on the web. Render it to a headset in stereo — that's VR. Composite it onto the real world — that's AR. At every step the component model is identical; what changes is the output device, exactly the way it changed when we went from browser tab to desktop window to native phone. Same React, different target. You are not learning 3D-React and then VR-React and then AR-React. You are learning that React describes a tree, and the tree can be pointed at increasingly immersive places.

The Thing This Whole Series Was Actually About

I saved this topic for last on purpose, because it makes the through-line of everything before it visible.

Look back at what we did. We fetched data and let a renderer reconcile the result. We managed state and let components re-render as a function of it. We moved React onto the desktop, onto phones, and now into three-dimensional space — and at every single stop, the same mental model carried: describe what the UI should be for a given state, and let a renderer make it real on whatever the target happens to be. The target was a browser, then a native window, then a native view, then a scene graph. The model never changed. That's not a coincidence you stumble on at article thirty — it's the thing the whole series was quietly teaching under the cover of specific problems.

React is not a DOM library. It is a way of describing UI as a function of state, with a renderer that reconciles your description against some target. The DOM was always just the first target.

That's why a React developer can move across this entire landscape — web, desktop, mobile, 3D, immersive — without starting over each time. The specifics are real and each one takes genuine learning, as every article in this series insisted. But the foundation is portable in a way that's rare in software, and 3D is the clearest proof: the moment <div> becomes <mesh> and nothing else about how you think has to change, you understand what you actually learned. You didn't learn the DOM. You learned React.

How I'd Approach It — and Where the Series Lands

Strip it to decisions:

• 3D isn't a hack on top of React. A scene is a tree, React renders trees, and React Three Fiber makes the elements 3D objects. <mesh> is the new <div>.
• Your whole component model transfers. Props, state, hooks, composition, reuse — all unchanged. Only the leaf primitives differ.
• VR and AR are the same tree, a different output device. Screen, headset, camera-composited world. Learn the scene, not three separate stacks.
• The portable asset was never the platform. It's the model: UI as a function of state, reconciled by a renderer against a target.

And that's where I'll leave the React Playbook. Thirty articles, from spinning up a project to rendering a cube in VR, and the honest summary of all of them is smaller than the page count suggests: pick tools that own the messy edges, keep your source of truth in one place, treat the client as untrusted and the boundary as sacred, and describe your UI as a function of state so it can follow you to whatever comes next. The specific libraries will churn — some of the ones I recommended will be replaced, and that's fine. The way of thinking is the part that lasts, and if this series left you with that instead of a list of dependencies, it did its job.

Thanks for reading this far. If the Playbook changed how you approach even one of these problems — or if you disagree with where I landed on some of them, which is entirely fair — I'd genuinely like to hear about it. That's the conversation that makes writing thirty of these worth it.

The single most useful thing to get straight about React Native is a slogan, and it's one people consistently misquote. The promise was never "write once, run anywhere." It was "learn once, write anywhere" — and the difference between those two words is the entire reason web developers either love React Native or feel betrayed by it.

Because here's what actually transfers to mobile: your React knowledge. Components, props, state, hooks, the mental model of describing UI as a function of data — all of it, intact, on day one. You are not starting over. What does not transfer is a lot of your code and, more subtly, a lot of your instincts. The <div> you've typed a hundred thousand times doesn't exist. CSS as you know it doesn't exist. The layout habits your fingers have memorized quietly stop working. So you arrive on mobile fluent in the language and unfamiliar with the streets, and whether that feels empowering or frustrating comes down entirely to expecting it.

This article is about drawing that line honestly — what your React experience genuinely buys you on mobile, and where it stops — so you show up expecting "learn once," not "write once," and don't waste a week being angry at the wall.

There Is No DOM. That's the Whole Shift.

Start with the concept that reorganizes everything else: React Native does not render to a browser, because there is no browser. Your components render to actual native platform views — a real iOS UIView, a real Android widget. React is the engine describing the UI; the thing it draws is native, not HTML.

This is why the primitives change. You don't write <div> and <span> and <p>, because those are HTML and there's no HTML here. You write <View> and <Text>, which map to genuine native components:

import { View, Text, Pressable } from 'react-native';

export function Greeting({ name }: { name: string }) {
  return (
    <View style={styles.card}>
      <Text style={styles.title}>Hi {name}</Text>
      <Pressable onPress={() => console.log('tapped')}>
        <Text>Tap me</Text>
      </Pressable>
    </View>
  );
}

Notice how familiar the shape is — it's components, props, a style prop, an event handler. And notice how many small things are different: View not div, Text wrapping every piece of text (you can't just drop a bare string like in HTML), onPress not onClick, Pressable instead of a button. That's "learn once, write anywhere" in miniature — the shape of your React knowledge fits perfectly, and every specific has to be relearned. The engine is the same; the vocabulary is new.

Styling: It Looks Like CSS and Isn't

The place this bites hardest, and the one worth dwelling on, is styling — because it looks close enough to CSS that you trust it, then it violates that trust.

React Native styling resembles CSS: you write style objects with camelCased properties, and many familiar names work. But it is not CSS, and the differences are exactly the ones your instincts will trip over. There are no cascading stylesheets, no selectors, no inheritance in the way you rely on — styles are explicit, per-component objects. There's no display: block versus inline. Most jarring of all: everything is flexbox, and it's vertical by default. On the web, flexDirection defaults to row; in React Native it defaults to column, because a phone screen is tall. Your web layout muscle memory, built on horizontal-by-default flow, is subtly wrong on every screen until you internalize the flip.

import { StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  card: {
    // flexDirection defaults to 'column' here — the opposite of the web.
    padding: 16,
    backgroundColor: '#fff',
  },
  title: { fontSize: 18, fontWeight: '600' },
});

None of this is hard. It's just different, and the danger is precisely that it looks similar enough that you don't respect the difference and spend an afternoon confused why your row is a column. Expect styling to be "CSS-flavored, not CSS," and the friction drops away. Treat it as the CSS you know and it will quietly punish you.

Just Use Expo

A practical fork, stated plainly because it saves the most pain: when you start a React Native project, use Expo. Bare React Native drops you into native build toolchains — Xcode, Android Studio, native dependency management — which is a heavy, platform-specific world that has nothing to do with React and everything to do with mobile plumbing you didn't sign up to learn on day one.

Expo is to React Native roughly what a good meta-framework is to React on the web: it owns the miserable setup and configuration so you can stay in the part you're good at. It handles the build tooling, gives you a clean managed workflow, and bundles access to native device APIs — camera, location, notifications — behind simple JavaScript, so reaching for the camera doesn't mean touching native code. It's the same lesson this whole series keeps landing on: don't hand-assemble the plumbing when a well-made tool already owns it. For the overwhelming majority of apps, Expo is simply the right starting point, and starting bare is a choice you should have a specific reason for.

The Instinct That Actually Needs Retraining

Beyond the vocabulary, there's a deeper adjustment, and it's the one that separates a web app running on a phone from an app that belongs there. Mobile is not a small desktop, and users can feel the difference instantly.

Touch is not a mouse. There's no hover — a whole category of web interaction just doesn't exist, and designs that lean on it fall flat. Targets have to be finger-sized, not cursor-precise. Gestures — swipe, long-press, pull-to-refresh — are expected vocabulary, not enhancements. Platform conventions differ, and iOS and Android users each have expectations about how navigation and controls should feel that a lowest-common-denominator layout ignores at its peril. And the device itself imposes realities the desktop rarely forces you to think about: constrained screens, variable network, battery, memory. The web developer's instinct to fill horizontal space, to treat the network as reliable, to assume hover and precise pointing — those instincts need retraining, and the app quality lives in that retraining far more than in the syntax.

This is the honest edge of "learn once, write anywhere": your React transfers, but your sense of what a good interface is has to expand from the web's assumptions to the phone's. That's not a knock on React Native — it's the reality of the platform being genuinely native, which is the whole point of using it.

How I'd Approach It

Strip it to decisions:

• It's "learn once," not "write once." Your React knowledge transfers whole; a lot of your code and instincts don't. Expect that and the wall becomes a curriculum.
• There is no DOM. View and Text, not div and span; onPress, not onClick. You render to real native views.
• Styling is CSS-flavored, not CSS. No cascade, no selectors, flexbox everywhere, and column-by-default. Respect the difference instead of trusting the resemblance.
• Use Expo. It owns the native build plumbing so you stay in React. Go bare only with a specific reason.
• Retrain your interface instincts. Touch, gestures, finger targets, platform conventions, device limits — mobile is native, not a narrow desktop.

The reason React Native either delights or frustrates comes down to which promise you showed up believing. Arrive expecting "write once, run everywhere" and every difference feels like a broken promise. Arrive expecting "learn once, write anywhere" and the exact same differences feel like a reasonable tax on real native rendering — you keep the expensive thing, your React fluency, and pay for the platform specifics, which is a genuinely good trade. The knowledge is the asset. The code was always going to be somewhat local to where it runs.

For the final article, the series leaves flat screens behind completely: React in VR and AR — where the same component model gets pointed at three-dimensional space, and what it means to write <mesh> instead of <div>.

If you're a web developer eyeing your first React Native project and bracing for a total restart, don't — it's far more transfer than restart, once you know which parts are which. Tell me what your app needs to do on the phone and I'll tell you where your web instincts will help and where they'll trip you.

There's a specific moment where the desktop pitch becomes irresistible. You've built a genuinely good React app, it lives in a browser tab, and someone asks "can we make it a real app?" — with a dock icon, a name, a window of its own. And the answer is yes, easily, with the same React code you already have. Electron and Tauri will both wrap it into a program that installs like any native app. The demo takes an afternoon and feels like magic.

So the tempting question is "how do I turn my React app into a desktop app," and it's the wrong one to lead with. The right question — the one that actually determines whether this is worth doing and which tool to reach for — is what do I gain by leaving the browser at all? Because a desktop wrapper that just shows your website in a frameless window is a worse browser tab: heavier, harder to update, and offering the user nothing they didn't already have. The whole justification for going desktop is the stuff a browser tab structurally cannot do, and if you don't need that stuff, you probably shouldn't be here.

This article is about that line — what the desktop actually buys you — and the honest tradeoff between the two tools that get you there.

What a Browser Tab Genuinely Can't Do

Start with the reason to leave the browser, because it's the whole point. A web page runs in a sandbox, deliberately walled off from the machine it's on — that's a security feature, not a limitation to complain about. But it means there are real capabilities a tab simply doesn't have, and those capabilities are your entire reason for going desktop.

Deep filesystem access — reading and writing arbitrary files on the user's disk, not the sandboxed trickle a browser allows. Real OS integration — a tray icon, native menus, global keyboard shortcuts that work when your app isn't focused, notifications that feel like the system's own. Talking to native or system-level resources the browser keeps off-limits. Working genuinely offline as a first-class program, not a web page hoping its service worker cached the right things. If your app needs one of these, the desktop isn't a nicety — it's the only place the feature can exist.

And the contrapositive matters just as much: if your app needs none of these — if it's fundamentally a web app that someone just wants to "feel" installed — then wrapping it in Electron mostly buys you weight and update headaches. Be honest about which side of that line you're on before you install anything. The desktop is for apps that need to touch the machine, not for apps that want a fancier bookmark.

The Two Tools, and the Real Tradeoff

Assuming you genuinely need out of the browser, there are two serious choices, and they represent a real architectural fork — not a matter of taste.

Electron is the established one — VS Code, Slack, Discord are all Electron. Its model is straightforward: it ships an entire copy of Chromium and Node.js inside your app. Your React runs in a real Chrome, and you get full Node in the backend process, so everything you know works exactly as expected. The cost is equally straightforward: because every app bundles its own whole browser, a trivial Electron app starts at a hundred-plus megabytes and a chunk of memory before it does anything. You're shipping a browser per app, times every Electron app the user has installed.

Tauri is the modern challenger with a different bet. Instead of bundling Chromium, it uses the operating system's own built-in webview — the browser engine already on the machine. And instead of Node, its backend is Rust. The payoff is dramatic: Tauri apps are a fraction of the size and memory, often a few megabytes instead of a hundred. The cost is the two edges of that same bet. Using the OS webview means you're rendering on WebKit on macOS, WebView2 on Windows — different engines — so you inherit cross-browser inconsistency as a desktop concern, which is a genuinely strange thing to have to test for in an installed app. And the native backend is Rust, so any serious system-level logic pulls you into a language your React team may not know.

                Electron                     Tauri
  Renderer      bundled Chromium (same       OS webview (WebKit / WebView2,
                everywhere)                  differs per platform)
  Backend       Node.js                      Rust
  App size      100MB+ (ships a browser)     a few MB (uses the OS's)
  You trade     size & memory                cross-engine testing + Rust

So the choice isn't "which is better," it's which cost you'd rather pay. Electron trades disk and memory for total consistency and a stack your web team already knows. Tauri trades a small footprint for cross-engine testing and a Rust backend. Neither is wrong; they're priced differently, and the right pick depends on whether size or familiarity hurts you more.

The Part That's Actually Different: Two Processes and a Bridge

Whichever you choose, there's one architectural shift that catches web developers off guard, and it's worth understanding because it shapes everything you build. A desktop app is not one environment — it's two, with a guarded door between them.

Your React UI runs in the renderer, which is still fundamentally a web context, sandboxed. The powerful stuff — filesystem, OS APIs, native calls — runs in a separate, privileged backend process (Node in Electron, Rust in Tauri). They can't just call each other's functions; they communicate over an explicit bridge, passing messages across. Your React code doesn't read a file directly — it asks the backend to, and the backend, which actually has the permission, does it and sends the result back.

// Renderer (your React UI): it cannot touch the disk itself.
// It asks the privileged backend to do it — Tauri example.
import { invoke } from '@tauri-apps/api/tauri';

async function loadNote(id: string) {
  // Crosses the bridge to the Rust backend, which has real file access.
  const contents = await invoke<string>('read_note', { id });
  return contents;
}

This should feel familiar, because it's the same pattern the whole series keeps circling: a sandboxed, untrusted frontend asking a privileged, trusted backend to do the dangerous thing — exactly like the client/server split in auth, just moved onto one machine. The renderer is the browser; the backend process is your server; the bridge is the API between them. Treat that boundary with the same seriousness — validate what crosses it, expose only the specific operations you mean to — and a desktop app stops feeling exotic and starts feeling like a client/server app you happen to ship in one installer.

How I'd Approach It

Strip it to decisions:

• Ask what you gain, not whether you can. If you don't need filesystem, OS integration, or true offline, the desktop is a heavier browser tab. Don't ship one for a fancy bookmark.
• The desktop is for touching the machine. Deep file access, tray/menus/global shortcuts, native resources, first-class offline — that's the whole reason to leave the browser.
• Electron vs Tauri is a cost choice, not a quality one. Electron: big and memory-hungry, but consistent and web-stack-familiar. Tauri: tiny, but cross-engine testing and a Rust backend.
• It's two processes with a bridge. Your React renderer asks a privileged backend to do the powerful things. Treat that bridge like a client/server boundary, because it is one.

The thing I want you to take from this is that "turn my React app into a desktop app" is the easy, uninteresting half. The wrapper is a solved afternoon. The real work — and the only justification for the extra weight and the two-process complexity — is the native power you reach for once you're out of the sandbox. Go desktop when your app needs the machine. Stay in the tab when it doesn't. And when you do go, remember you didn't escape the client/server split, you just packaged both halves into one window.

The next article stays off the web but changes machines entirely: React Native and mobile — where "same code, new platform" gets far more honest about what actually carries over and what doesn't.

If you're weighing a desktop build and can't tell whether you truly need to leave the browser, that's the exact question worth answering first — and it's usually clearer than it feels. Tell me what native capability you're reaching for and I'll tell you if the desktop is really the only place to get it.

Every team I've watched try to document their components starts in the same place: a page in the wiki. Someone writes up the Button — here are the variants, here's a screenshot, here's a table of props — and for about three weeks it's great. Then someone adds a loading prop and doesn't update the page. Then the primary color changes and the screenshot is now a lie. A month in, the docs describe a component that no longer exists, and the whole team has quietly learned to not trust them. So they read the source instead, and the docs rot in place, occasionally misleading a new hire.

This isn't a discipline problem, and treating it as one — "we just need to be better about updating the docs" — is why it keeps happening. People aren't lazy; the docs are structurally doomed. The reason is simple and it's the whole point of this article: the documentation lives in a different place than the code it describes. Two sources of truth, updated by two separate acts of will, and one of them always falls behind. You've seen this exact shape before — it's the same two-sources-of-truth failure as the real-time cache, just applied to prose instead of state.

So the question isn't "how do we write better component docs." It's "how do we make docs that can't drift" — and the answer is to stop writing docs that sit next to the code and start generating them from the code itself.

Why the Wiki Always Loses

Sit with why the wiki page decays, because the mechanism matters. When you change a component, updating its separate documentation is a second, optional action. The code change ships value on its own; the doc update is extra work with no immediate payoff, easy to defer, easy to forget, and nothing breaks when you skip it. So under any deadline — which is always — the doc update is the first thing to go. Multiply that across a team and a year, and every hand-maintained doc trends toward wrong.

The insight that fixes it is to remove the second action entirely. If the documentation is derived from the code rather than maintained alongside it, then changing the code changes the docs, automatically, with no act of will required. The drift becomes impossible not because everyone got more disciplined, but because there's no longer a gap for drift to live in. This is the same instinct as generating types from a schema or migrations from a model: one source of truth, everything else derived. Documentation is just another thing that should be derived, not duplicated.

The Props Table Should Come From the Props

The most concrete version of this: that table of props everyone hand-writes and forgets to update? It should not be hand-written. Your component's props are already fully described — in its TypeScript types. That's a machine-readable specification of every prop, its type, whether it's required, sitting right there in the code.

interface ButtonProps {
  /** Visual style of the button. */
  variant: 'primary' | 'secondary' | 'danger';
  /** Shows a spinner and disables interaction. */
  loading?: boolean;
  /** Called when the button is clicked. */
  onClick: () => void;
}

export function Button({ variant, loading, onClick }: ButtonProps) {
  /* ... */
}

Everything a props table would contain is in that interface — the names, the exact allowed values of variant, which props are optional, and even the descriptions in the doc comments. Tooling like Storybook reads those types directly and generates the props table for you. Add a prop, the table gains a row. Change variant's options, the table updates. Delete a prop, its row disappears. You didn't maintain anything — the documentation is a view of the types, and the types can't be wrong because they're the code that actually runs. The single most rot-prone piece of component docs becomes the single most reliable one, purely by deriving it instead of writing it.

Living Examples Beat Screenshots

The other half of component docs is showing the thing in use, and here the screenshot is the villain. A screenshot is a photograph of the component at one moment in the past — it stops being accurate the instant anything changes, and it can't show a single interactive state. Hover, focus, loading, disabled, the error variant — a static image shows none of it and silently goes stale on all of it.

The fix is the same move again: don't take a picture of the component, render the real component. A story in Storybook is a live instance of the actual component, mounted with real props, that you can interact with:

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = { component: Button };
export default meta;

export const Primary: StoryObj<typeof Button> = {
  args: { variant: 'primary', onClick: () => {} },
};

export const Loading: StoryObj<typeof Button> = {
  args: { variant: 'primary', loading: true, onClick: () => {} },
};

Those aren't images of a button — they're the button, running, with the exact props your app would pass. If the button changes, the stories change with it, because they are the component, not a snapshot of it. You can hover the real hover state, watch the real spinner, tab to the real focus ring. A screenshot documents what the component looked like once; a story documents what the component is right now, and stays honest by construction.

And there's a compounding benefit that ties back to the design conversation: a living component catalog is where designers and engineers actually agree on what exists. When the real Button, in all its states, is browsable in one place, "does this already exist?" has an answer you can see and click — which is the difference between reusing the component and rebuilding it slightly differently for the fifth time.

How I'd Approach It

Strip it to decisions:

• Separate docs always rot. It's not a discipline problem — it's two sources of truth. Stop maintaining docs next to the code.
• Derive, don't duplicate. Generate documentation from the code so changing the code changes the docs, automatically.
• The props table comes from the types. Your TypeScript interface already is the spec; let tooling render it. Never hand-write a props table.
• Render real components, not screenshots. A live story stays accurate and shows interactive states; an image is stale the moment you save it.
• A living catalog drives reuse. When every component is browsable in all its states, "does this exist?" becomes answerable — and things get reused instead of rebuilt.

The reason component docs have such a bad reputation is that almost everyone builds them to fail, then blames themselves when they do. A wiki page and a screenshot are drift waiting to happen, and no amount of resolve fixes a structural flaw. The shift that makes documentation actually last is to stop treating it as a thing you write and start treating it as a thing you derive — from the types, from the real components, from the code that's already the truth. Do that, and your docs stop being a chore you fall behind on and become a side effect of building the components at all. That's the only kind of documentation I've seen survive contact with a deadline.

This is where the "build a real app" spine of the series ends — from starting a project all the way through documenting what you built. The remaining articles step outside the browser entirely: next up, React on the desktop — when Electron or Tauri actually earns its place, and what changes when your React app is a window instead of a tab.

If your team has component docs that nobody trusts, it's almost certainly the separate-source-of-truth problem, and it's fixable without a documentation crusade. Tell me how your docs are set up and I'll tell you which piece to derive instead of write.

The way most engineers relate to a design file is as a target to hit. The designer hands over a Figma frame, and the job — as everyone tacitly agrees — is to make the screen look like the picture. Pixel for pixel, color for color. Reproduce it, get it approved, move on.

I want to push on that framing, because I think it's the root of a lot of avoidable pain. A design isn't a picture you copy. It's the first draft of your component architecture, whether anyone treats it that way or not. The structure of that screen — what repeats, what nests, what varies, where the boundaries fall — is the structure of the code you're about to write. Which means the most consequential architectural decisions in a feature are often made in a design tool, by someone thinking about spacing and hierarchy, long before an engineer opens their editor. And when the design's structure and the code's structure disagree, you get the codebases everyone recognizes: technically matching the mockup, quietly miserable to maintain.

So this article is about reading a design the way it deserves to be read — as architecture — and why that shift changes both what you build and how you work with the people who design it.

A Design Has Structure, Not Just Appearance

Look at any real screen and there are two different things present at once. There's the appearance — the colors, the fonts, the shadows, the exact pixels. And there's the structure — this card repeats six times, that button is the same button as the one on the other screen, this panel contains a header and a list, these three stats are the same shape with different data.

Reproducing appearance is the shallow job. Reading structure is the real one, because structure is what maps to components. When you see six cards, the architectural fact isn't "six cards" — it's "one Card component, rendered six times." When you see a button here that's clearly the same button as three other screens, the fact is "this is one shared Button, not a thing I restyle locally each time." The design is quietly telling you what your components are, what your reusable primitives are, and how they compose. A developer who only sees the picture reproduces the pixels and invents an ad-hoc structure underneath. A developer who reads the structure lets the design hand them their component boundaries for free.

A mockup shows you what the screen looks like. Read carefully, it also shows you what your components are, which ones repeat, and where they compose. The second reading is the one that keeps your codebase sane.

Same Component, Different States — the Thing Static Mockups Hide

Here's where the "design is a picture" framing does the most damage, and it's the single most valuable thing to internalize about prototyping for React.

A static mockup shows you one moment. But a React component is never one moment — it's every state that data can put it in. The screen you were handed shows a list with eight items. Your component also has to handle: zero items (the empty state), one item, hundreds (does it scroll, paginate, virtualize?), the loading moment before any data arrives, and the error case when the fetch fails. The mockup showed you one of five or six realities, and if you only build the one you were shown, you'll ship a component that looks perfect in the demo and breaks the first time real data is empty or slow.

This is why the most useful thing you can do with a design isn't to start coding it — it's to interrogate it. Before writing the component, I go looking for the states the mockup didn't show. What does this look like with no data? While it's loading? When it fails? When the text is three times longer than the placeholder? When there are two hundred rows instead of eight? Half the time the honest answer is "the designer didn't think about that yet," and surfacing it before you build is enormously cheaper than discovering it in QA. The static frame is the happy path; your component is responsible for all the paths, and prototyping is where you find the missing ones.

This Is a Conversation, Not a Handoff

That interrogation is exactly why I don't think of design-to-code as a handoff. A handoff is one-directional: design finishes, throws the result over a wall, engineering catches it. But the questions that matter — what are the empty and error states, is this really the same component as that one, does this pattern already exist in our system — can only be answered together, and answering them early is where the leverage is.

When engineering engages with design during prototyping instead of after, a few things change. Reusable pieces get spotted before they're built five slightly-different times. Missing states get designed instead of improvised by whichever developer hits them first. And the design starts to align with the components that already exist — which connects straight back to the design systems idea: a prototype built from the components you already have is a prototype that ships in a fraction of the time, because the answer to "how do I build this" is "you mostly already did." The handoff model forecloses all of that by making the conversation happen too late, after the structural decisions have already hardened on both sides.

I'm not arguing engineers should design. I'm arguing that the boundary between "design work" and "architecture work" is far blurrier than the org chart suggests, and pretending it's a clean line — a wall with a handoff over it — is how you get designs that fight the code and code that fights the design.

How I'd Approach It

Strip it to decisions:

• Read a design for structure, not just appearance. What repeats, what nests, what varies — that's your component tree, handed to you.
• A static mockup is one state. Before coding, hunt for the ones it hides: empty, loading, error, overflow, huge data. Build all the realities, not the one you were shown.
• Interrogate before you implement. The cheapest place to discover a missing state is a design review, not QA.
• Treat it as a conversation, not a handoff. Engaging during prototyping surfaces reuse and missing states while they're still cheap to fix.
• Prototype from your existing components. A design aligned to the system you already have ships far faster than one drawn from scratch.

The reframe that changed how I work is small but load-bearing: the design tool is where architecture starts, not where it waits. The person arranging cards and spacing is making decisions about repetition, hierarchy, and composition — the exact decisions I'll be encoding in components an hour later. When I treat the mockup as a picture to copy, I throw all that structural information away and rebuild it, worse, in code. When I treat it as the first draft of the architecture, the design does half the hard thinking for me — and the half it left out becomes a conversation instead of a bug.

Next, the flip side of building components well: documenting them — so the reusable pieces you and your designers just agreed on actually get reused instead of quietly rebuilt for the fifth time.

If your team's design-to-code process feels like reproducing pictures and constantly rediscovering missing states in QA, that's the handoff model doing its usual damage. Tell me where it hurts — the reuse, the missing states, the drift — and I'll tell you where the conversation needs to move earlier.

"When someone signs up, just send them a welcome email." It's the kind of request that gets tossed into a standup like it's nothing, and the person saying it genuinely believes it's a five-minute task. Send an email. How hard could it be?

Here's the thing that makes email sneaky: the part you'd expect to be hard is trivial, and the part you'd expect to be trivial is where the whole thing lives. Triggering an email from your app is a single function call. Actually getting that email into someone's inbox — not their spam folder, not bounced, not silently dropped — is a genuinely deep backend problem involving deliverability, sender reputation, authentication protocols, and a rendering environment stuck two decades in the past. And almost none of it is a React problem, which is exactly why it catches frontend developers off guard.

So this article is a map of where the real work is. Because the most useful thing I can tell you about email in a React app is which parts to not do yourself, and why the boundary sits where it does.

The Line: The Client Never Sends Email

Start with the hard boundary, because it's the one people are tempted to cross. Your React app does not send email. Ever. It triggers a request to your backend, and your backend sends the email.

This isn't a style preference, it's a security wall. Sending email requires credentials — API keys for your email service — and anything in your React bundle is public. Ship that key to the client and you've handed the entire internet the ability to send email as you, which means spammers now have a free megaphone wearing your domain's reputation. Within days your domain is blacklisted and even your legitimate mail stops arriving. So the flow is always the same shape as payments and auth: the client asks, the server acts, and the credential never leaves the server.

// The client's entire involvement: ask the backend to do it.
async function requestWelcomeEmail(userId: string) {
  await fetch('/api/emails/welcome', {
    method: 'POST',
    body: JSON.stringify({ userId }),
  });
}

That's the whole frontend story. There is no sendEmail in your components, no email API key in your environment variables with a public prefix, no SMTP in the browser. The moment email touches the client, you've done it wrong. Everything interesting from here happens on the server.

Why You Don't Talk to SMTP Yourself

On the backend, the naive mental model is that you connect to a mail server over SMTP and send. You can do that. You shouldn't, and understanding why is the core of this whole topic.

Getting an email delivered is not about transmitting it — it's about being trusted enough that the receiving server puts it in the inbox instead of the spam folder or the trash. That trust is a system: your domain needs authentication records (SPF, DKIM, DMARC) that prove you're allowed to send as your domain; your sending IP needs a reputation built over time; you need to handle bounces and complaints so you stop mailing dead addresses; and you need to not trip the spam filters that treat unknown senders with suspicion. Running your own mail server means owning all of that — reputation, blacklist monitoring, authentication, the works — and it is a full-time infrastructure job that has nothing to do with your product.

This is why transactional email services — Resend, Postmark, SendGrid — exist, and why using one isn't laziness but the correct architecture. They've spent years building sender reputation, they handle the authentication protocols, they manage bounces and deliverability, and they give you a clean API. Your backend calls that API; the hard, invisible work of actually getting delivered is theirs.

// Your server. The service owns deliverability; you own intent.
import { Resend } from 'resend';
const resend = new Resend(process.env.RESEND_API_KEY); // server-only secret

app.post('/api/emails/welcome', async (req, res) => {
  const user = await getUser(req.body.userId);
  await resend.emails.send({
    from: 'hello@yourdomain.com',
    to: user.email,
    subject: 'Welcome aboard',
    react: <WelcomeEmail name={user.name} />, // more on this below
  });
  res.json({ queued: true });
});

Same lesson as every article in this series: the raw capability (SMTP) is a footgun, and the value is a service that owns the messy, reputation-dependent edges. You are buying deliverability, not a send button.

The Genuinely Weird Part: Email Rendering Is Stuck in 2005

Here's the one place your React skills partly transfer, and it comes with a nasty surprise. You'd assume you can build an email template with normal components and modern CSS. You cannot, and this trips up every frontend developer exactly once.

Email clients — Outlook especially, but not only — render HTML with engines that are decades behind browsers. No flexbox, no grid, no modern CSS, inconsistent support for things you consider baseline. The reliable way to lay out an email is tables, the way the web worked in 2005, with inlined styles because <style> blocks get stripped. Hand-writing that is miserable and easy to get wrong across the dozens of clients your users actually use.

The modern rescue is that you can write email templates as React components — using a library like React Email — and it compiles them down to the table-based, inline-styled HTML that survives Outlook. You get to think in components; the library deals with the 2005 rendering reality underneath.

import { Html, Button, Text } from '@react-email/components';

export function WelcomeEmail({ name }: { name: string }) {
  return (
    <Html>
      <Text>Hi {name}, glad you're here.</Text>
      <Button href="https://yourdomain.com/start">Get started</Button>
    </Html>
  );
}

That looks like a normal component, but <Button> and <Text> aren't rendering <button> and <p> — they emit the gnarly, table-wrapped, inline-styled markup that renders consistently from Gmail to a decade-old Outlook. It's the same pattern once more: a library absorbing an ugly reality so you can work in a sane abstraction. You write React; it ships something that would make you cry if you had to write it by hand.

How I'd Approach It

Strip it to decisions:

• The client never sends email. It asks the backend. The API key is a server-only secret — leaking it burns your domain's reputation.
• Don't run your own mail server. Deliverability is a reputation-and-authentication system, not a transmission problem. Use a transactional email service.
• You're buying deliverability, not a send button. SPF/DKIM/DMARC, bounce handling, and IP reputation are the actual product these services sell.
• Email rendering is stuck in the past. Write templates as React components via React Email; let it compile down to the table-based HTML that survives Outlook.

The reason "just send an email" turns into a week is that the sentence hides the entire iceberg. The tip — trigger a send — is the trivial thing everyone pictures. The mass underneath is deliverability, authentication, reputation, and a rendering environment that predates most of the developers working on it. The good news is that the whole iceberg is a solved, buyable problem: a transactional service for delivery, React Email for templates, and a hard rule that none of it touches the client. Get the boundary right and email goes back to being the five-minute task everyone assumed it was — because someone else already did the hard 95%.

Next, the series shifts from wiring things up to thinking about them differently: design prototyping for React — where design work stops being visual and starts being architectural, and why that handoff matters more than people admit.

If you've got emails landing in spam, or a template that looks perfect everywhere except Outlook, those are the two classic email potholes — deliverability and rendering — and both have known fixes. Tell me which one's biting you and I'll point you at the layer to check.

Adding a file upload feels like a solved problem. You drop an <input type="file"> on the page, grab the file in an onChange, POST it to an endpoint. Ten minutes of work, and on your machine — with a 40KB avatar and localhost — it works flawlessly. You move on.

Then it meets reality. Someone uploads a two-gigabyte video from hotel wifi. Someone's connection drops at 90%. Someone picks a 500MB file and your server, which happily buffered the 40KB avatar into memory, tries to do the same with half a gigabyte and falls over. The file input was never the hard part. The hard part is that a file is a large, unreliable stream of bytes that has to travel from an untrusted browser, across a flaky network, to somewhere it can actually live — and every one of those words is a problem.

So this article isn't about the input element. It's about the thing underneath: moving real files, at real sizes, over real networks, without melting your server or lying to your user about what's happening.

The First Decision: Your Server Shouldn't Touch the File

Here's the instinct that causes most upload pain: the file goes browser → your server → storage. Your React app POSTs to your API, your API receives the bytes and forwards them to S3 or wherever. It's the obvious shape, and it's the wrong one for anything but tiny files.

Why it's wrong: your server now has to hold the file — in memory or on disk — while it passes through. A handful of users uploading large files at once and your server is doing nothing but shuttling bytes, burning memory and connection time on work that isn't yours. You've turned your application server into a file relay, and file relays are exactly what dedicated storage services already are, better than you.

The pattern that fixes it is presigned uploads, and it's worth understanding because it reshapes the whole flow. The file goes browser → storage directly, and your server's only job is to hand out permission. The client asks your API "I want to upload this file," your API asks the storage service for a short-lived, single-purpose URL, and hands that URL back. The browser then uploads straight to storage. Your bytes never touch your server.

// Your server: it never sees the file. It only grants permission.
app.post('/api/uploads/sign', async (req, res) => {
  const { filename, contentType } = req.body;

  // Ask storage for a short-lived URL scoped to this one upload.
  const uploadUrl = await storage.createPresignedUrl({
    key: `uploads/${crypto.randomUUID()}/${filename}`,
    contentType,
    expiresIn: 60, // seconds — the URL is useless after that
  });

  res.json({ uploadUrl });
});

// The browser: uploads the bytes directly to storage, not to you.
async function uploadFile(file: File) {
  const { uploadUrl } = await fetch('/api/uploads/sign', {
    method: 'POST',
    body: JSON.stringify({ filename: file.name, contentType: file.type }),
  }).then((r) => r.json());

  await fetch(uploadUrl, { method: 'PUT', body: file }); // straight to storage
}

Look at how the responsibilities split. Your server does a tiny, fast, cheap thing — validate the request, mint a scoped URL, respond. The multi-gigabyte transfer happens between the browser and a service built for exactly that. This is the same server-is-the-authority, client-does-the-work split from the auth and payments articles: your backend controls permission, but it doesn't do the heavy lifting it has no business doing.

The Second Reality: The Upload Is a Process, Not a Request

Once the file is going straight to storage, the next thing to accept is that a large upload is not an event that happens — it's a process that unfolds over time, and your UI has to treat it that way.

A 40KB avatar uploads instantly, so you can pretend it's a normal request. A 500MB file takes a minute or more, and during that minute the user is staring at your interface wondering if it's working. If you show them a frozen spinner, they'll assume it hung and refresh — killing the upload. So progress isn't a nice-to-have here; it's the difference between a feature that works and one users abort halfway. You have to report how far along the bytes are:

function uploadWithProgress(url: string, file: File, onProgress: (pct: number) => void) {
  const xhr = new XMLHttpRequest();
  xhr.upload.addEventListener('progress', (e) => {
    if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
  });
  xhr.open('PUT', url);
  xhr.send(file);
}

That xhr.upload.progress event — one of the few times raw XMLHttpRequest still earns its place over fetch, which can't report upload progress — is what lets you draw a real progress bar. And a real progress bar changes user behavior: people wait for a bar that moves, and they abandon a spinner that doesn't. The technical work of measuring progress is small; the UX consequence of showing it is large.

The Third Reality: Big Files Need to Survive a Dropped Connection

Now the hardest layer, and the one that separates a toy from a product: what happens at 90% when the wifi blinks?

With a single PUT of the whole file, the answer is brutal — the upload fails and starts over from zero. For a 40KB file, who cares. For a 2GB file on a shaky connection, "start over from zero" may mean it never completes, because the odds of an uninterrupted multi-gigabyte transfer on bad wifi are genuinely low. The single-request model has a size ceiling baked in, and above it, uploads just don't finish.

The answer is chunked (multipart) uploads: split the file into pieces, upload each piece independently, and reassemble them in storage. Now a dropped connection costs you one chunk, not the whole file — you retry that chunk and continue. Uploads become resumable, and the size ceiling effectively disappears.

I want to be honest about the tradeoff, because this is where the "it's just an input" fantasy fully dies: chunking is genuinely more complex. You're tracking which chunks succeeded, retrying the ones that didn't, handling out-of-order completion, and telling storage to stitch them back together. This is real coordination logic, and it's exactly why you don't hand-roll it. Storage services expose multipart upload APIs, and libraries like Uppy wrap the whole thing — chunking, retries, progress, resumability — behind a component. The same lesson as every article in this series: the raw capability is a footgun, and the value is a library that owns the messy edges so you spend your attention on your product, not on retry bookkeeping.

Don't Forget: The File Is Untrusted

One security note that's too important to skip, because uploads are a classic attack surface. A file arriving from a browser is user input, and the same rule from the payments and auth articles applies: never trust it.

The client can claim a file is a 2MB image and actually send a 2GB executable. It can lie about the content type. So validation belongs on the boundary you control — size limits, allowed types, and ideally scanning — enforced when you mint the presigned URL and verified again on the storage side, never solely in the browser where a hostile user can bypass it. Client-side checks are for UX (tell the user "that's too big" before they wait); server-side checks are for safety. You need both, and you must never mistake the first for the second.

How I'd Approach It

Strip it to decisions:

• Your server hands out permission, not bytes. Use presigned URLs so the file goes browser → storage directly. Don't turn your API into a file relay.
• Treat the upload as a process. Show real progress from xhr.upload. A moving bar is why users wait instead of refreshing.
• Chunk large files. Multipart uploads make transfers resumable and remove the size ceiling. Don't hand-roll it — use the storage API via a library.
• The file is untrusted input. Validate size and type on the server boundary, not just in the browser. Client checks are UX; server checks are security.

The reason file upload is a rite of passage is that the easy version and the real version look identical right up until the file gets big or the network gets bad. The input, the POST, the success toast — all of that is the 10% you can write in your sleep. The 90% is respecting that you're moving a large, untrusted, interruptible thing across a connection you don't control, to a service that should be doing the heavy carrying instead of your server. Get that shape right — permission from your backend, bytes to real storage, progress and resumability for the user — and uploads stop being the feature that falls over in production.

Next, another piece of infrastructure that looks trivial and isn't: sending email from a React app — why "just send an email" is a backend problem wearing a frontend costume, and where the real work hides.

If you've got an upload that works for small files and dies on big ones, that's the single-request ceiling, and it's the most common upload bug there is. Tell me where it breaks — the server memory, the timeout, the 90% drop — and I'll tell you which layer is missing.

A date is just a value. It sits there in your data looking as harmless as a string or a number, and for a while it behaves. Then one day a user in another timezone reports that their meeting shows an hour off, or a "created today" badge appears on something made yesterday, or a date field creeps backward by one day every single time someone saves the form. Suddenly the most boring data type in your app is the source of the weirdest bug in your tracker.

Time is deceptive because it looks simple and is not. The complexity is real and mostly invisible on the machine you develop on, because your machine has one timezone, and so the entire category of problems — timezones, daylight saving, what "midnight" even means — stays hidden until someone in a different part of the world hits it. And they always hit it, usually in production, usually at an hour that makes the bug's name feel personal.

So this article is about the small number of ideas that keep time from breaking a React app. Not a date-library tour — a way of thinking about time that makes the whole class of bugs stop happening.

The One Rule That Prevents Most of It

If you take nothing else from this: store and transmit time in UTC. Convert to the user's local timezone only for display. That's it. That single discipline, applied without exception, eliminates the majority of time bugs before they can form.

A timestamp is a fact — the exact instant something happened. A timezone is a lens for viewing that fact. Store the fact once, in UTC. Choose the lens at the last possible moment, at render.

Here's why this works. An instant in time is absolute — the moment a user clicked "submit" is the same moment everywhere on Earth. What differs is how you describe it: 3 PM in London, 10 AM in New York, same instant. The bug factory is storing or comparing times in local terms, because then "the same moment" has many different labels and they drift against each other. Store the absolute fact in UTC, keep it in UTC through your database and your API, and only bend it into a human's local timezone when you're about to show it to that specific human. Timezone becomes a display concern, which is the only place it belongs.

The mirror-image mistake — the one that produces the "date shifts by a day every save" bug — is round-tripping a date through local time on the way in and out, so each save nudges it by the offset. Keep the storage UTC and the conversion display-only, and that whole genre of bug can't happen.

Why new Date() Keeps Betraying You

The native Date object is where good intentions go to die, and it's worth being specific about why, because the failure is silent.

Date is implicitly local. The moment you parse or construct one, it quietly adopts the runtime's timezone — which is your laptop in development and the user's machine (or worse, a server in yet another zone) in production. So code that looks correct on your screen produces different results for different users, and you won't see it, because your machine only ever shows you your own timezone's answer.

// Looks innocent. Behaves differently depending on where it runs.
const d = new Date('2026-07-21'); // midnight UTC... interpreted as LOCAL
d.getDate(); // 21 in London. 20 in New York. Same code, different day.

That getDate() returning 20 for a New York user is the entire "off by one day" bug in miniature — the string is midnight UTC, but Date shows it through local eyes, and New York's local eyes are still on the 20th. Nothing threw an error. The value is just wrong, for some people, some of the time, which is the worst kind of wrong.

Reach for a Real Library — and Watch Temporal

Because Date is a minefield, the long-standing answer is a library that makes timezone handling explicit instead of implicit. date-fns is my usual pick — modular, tree-shakeable, and its companion date-fns-tz makes conversions something you state rather than something that happens to you:

import { formatInTimeZone } from 'date-fns-tz';

// The instant is stored in UTC. Display it in the user's zone, explicitly.
const utcInstant = '2026-07-21T23:30:00Z';
formatInTimeZone(utcInstant, 'America/New_York', 'yyyy-MM-dd HH:mm'); // "2026-07-21 19:30"
formatInTimeZone(utcInstant, 'Asia/Tokyo', 'yyyy-MM-dd HH:mm');      // "2026-07-22 08:30"

Notice the same UTC instant renders as the 21st in New York and the 22nd in Tokyo — correctly, because the conversion is explicit and timezone-aware, not left to whatever Date guesses. You're stating the lens instead of inheriting it.

The genuinely good news is that the language itself is fixing this. Temporal — the new built-in date/time API — is designed specifically to end the Date era: immutable objects, explicit timezone handling, no more implicit-local footguns. It's landing in engines now, and it's the direction everything moves. If you're starting fresh, it's worth watching closely and reaching for as it stabilizes; it makes the "be explicit about timezones" discipline the default instead of something you bolt on with a library.

The Traps That Remain

Even with the UTC rule and a real library, a few sharp edges stay sharp, and they're worth naming because each has bitten real apps.

Daylight saving time means some days don't have 24 hours and some local times don't exist at all — the clock jumps forward and 2:30 AM simply never happened on that date. Any code doing time math by adding 24 * 60 * 60 * 1000 milliseconds and calling it "a day" is wrong twice a year; a real library that adds calendar days handles it, hand-rolled arithmetic does not.

"Midnight" and "today" are not absolute either — they're timezone-bound. "Show me everything from today" means a different range of instants for a user in Los Angeles than one in Berlin, and if your backend computes "today" in the server's timezone, half your users see the wrong day's data. "Today" is always someone's today, and you have to decide whose.

And serialization is where discipline leaks: the safe way to put a date on the wire is ISO 8601 in UTC (that trailing Z), because it's unambiguous. A date formatted for humans — or worse, a bare new Date().toString() — is a guessing game for whatever parses it next. Keep the API boundary UTC and ISO, and convert to human-readable strictly at the edges, at display.

How I'd Approach It

Strip it to decisions:

• Store and send UTC. Convert only for display. The single rule that prevents most time bugs.
• Distrust new Date(). It's implicitly local, so it's implicitly wrong for someone. Don't do timezone logic with it.
• Use a real library (date-fns today) and make conversions explicit. Watch Temporal and adopt it as it lands.
• Respect DST and "today." A day isn't always 24 hours, and "today" is always somebody's local today.
• Serialize as ISO 8601 UTC. Unambiguous on the wire; humanize only at the edge.

The reason time bugs are so embarrassing is that they're invisible right up until they're not. Everything works on your machine, in your timezone, during the months without a DST transition — and then a user in Tokyo, or a clock change in November, or a "today" filter computed in the wrong zone quietly serves the wrong answer, and it looks like the code was never tested. It was tested. It was just tested in one timezone. Treating time as an absolute UTC fact that you view through a local lens only at the very end is the habit that makes those 2 AM bugs stop being yours.

Next, a different kind of unglamorous-but-treacherous: file uploads in React — progress, chunking, and the surprisingly deep problem of moving a large file from a browser to somewhere it can live.

If you've got a date that shifts by a day, a badge that says "today" when it isn't, or a meeting an hour off for some users, that's almost always a UTC-vs-local leak. Tell me where the wrong value shows up and I'll tell you which conversion is doing it.

On the surface, taking a payment looks like the most ordinary thing in the world: a form with some fields, a submit button, a success message. You've built a hundred forms. This is just a form where one of the fields happens to be a card number.

It is not just a form, and the card number is exactly why. That field is radioactive. The moment a real card number touches your servers, you've walked into PCI compliance — a wall of security obligations that exists for very good reasons and that you do not want to be responsible for. And the "success message" hides the second trap: unlike every other form you've built, you don't actually know the outcome when the user clicks submit. The payment confirms asynchronously, somewhere you can't see, and the single most expensive mistake in this entire domain is letting your React app believe it got paid because a client-side callback said so.

So this article isn't a Stripe tutorial. It's about the two lines that matter — the one that keeps the card number away from you, and the one that decides where "you got paid" is actually true — because getting those two lines right is the whole job, and getting either wrong is how you end up either liable or robbed.

The First Line: Never Touch the Card Number

Start with the rule that shapes everything else: the raw card number must never reach your server. Not to "just pass it through," not to log it, not for a millisecond. The instant it does, you're in PCI-compliance scope, and that is a burden measured in audits and dread, not code.

The whole architecture of a modern payments provider exists to keep you out of that scope, and the mechanism is worth understanding because it's genuinely clever. You don't build the card input. Stripe does — via Stripe Elements, an iframe-based field that Stripe hosts and controls. The card number is typed into their iframe, on your page, and it goes straight to Stripe. Your JavaScript can't read it. Your server never sees it. What you get back instead is a token — a harmless reference that means "Stripe is holding a card for you" — and that is what flows through your system.

import { PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';

export function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!stripe || !elements) return;

    // Stripe collects the card in its own iframe and confirms directly.
    // The card number never touches your JS or your server.
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: { return_url: 'https://example.com/order/complete' },
    });

    if (error) {
      // Show the user the reason. This is the "did it start" answer,
      // NOT the "did it succeed" answer.
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit">Pay</button>
    </form>
  );
}

Look at what your code never handles: the card number itself. <PaymentElement /> is Stripe's iframe living inside your form. You render it, you style around it, and you stay completely out of scope for the one piece of data that would otherwise make you liable. This is the buy-don't-build principle from the auth article at its most extreme — the risk here is so high that building it yourself isn't a trade-off, it's a mistake.

The Second Line: The Client Doesn't Decide

Now the subtler and more dangerous part. The payment is initiated in the browser, but the browser is the last place that should decide whether it succeeded.

Here's why this bites people. The naive flow: user pays, Stripe's client call resolves, you show "Payment successful!" and mark the order as paid in your UI. It demos perfectly. And it's exploitable and unreliable, because the client is an environment you don't control. The user closes the tab the instant before the callback fires — the card was charged, your app never knew. The network drops after the charge but before the response — same. And a hostile user can straight up call your "mark as paid" endpoint without paying at all, because anything the client asserts, a client can fake.

The answer is the one that runs through this whole series: the client is untrusted; the server is the source of truth. The real confirmation doesn't come from your React callback. It comes from Stripe, server-to-server, via a webhook — Stripe calls your backend to say "this payment actually succeeded," and that server-side event is the only thing allowed to mark an order as paid.

// On your server — the ONLY place an order becomes "paid".
app.post('/webhooks/stripe', async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    WEBHOOK_SECRET, // proves the call really came from Stripe
  );

  if (event.type === 'payment_intent.succeeded') {
    const intent = event.data.object;
    await markOrderPaid(intent.metadata.orderId); // trusted truth
  }

  res.json({ received: true });
});

So the client's job and the server's job split cleanly. The client starts the payment and shows a hopeful "we're processing your order." The server, via the webhook, confirms it and flips the order to paid. Those are two different facts arriving through two different channels, and conflating them — treating the client's optimistic result as the settled truth — is the bug that gets apps double-charging, under-charging, or handing out product for free.

The client can tell you a payment started. Only the server, via the provider's webhook, can tell you it succeeded. Never let the browser be the thing that says "paid."

This maps exactly onto the server-state idea from the auth article: the important truth lives on the server, and the client holds a hopeful, possibly-stale view of it. Payments are the highest-stakes version of that same pattern, which is why the discipline matters more here than anywhere.

So How Hard Is It, Really?

Honestly? Less than the fear suggests, if you respect the two lines. Stripe has done the genuinely hard parts — the card handling, the PCI scope, the fraud tooling. What's left for you is smaller than people expect, but it's unforgiving about correctness.

Your real work is three things. Render Stripe's Element so the card never touches you — mechanical, and Stripe hands you the components. Kick off the payment from the client and, critically, treat the client-side result as "started," not "done." And build the webhook handler on your backend as the sole authority that marks an order paid, verifying the signature so nobody can forge that call. That's the shape of it. It's not a huge amount of code. It's a small amount of code where being casually wrong costs actual money, which is a very different kind of hard than "lots of code."

How I'd Approach It

Strip it to decisions:

• The card number is radioactive. Use Stripe Elements so it never touches your JS or server. Don't negotiate with PCI scope — avoid it.
• The client starts the payment; it does not confirm it. Show "processing," never "paid," from a client callback.
• The webhook is the source of truth. An order becomes paid on your server, when Stripe tells your server it succeeded — and never before.
• Verify the webhook signature. Otherwise anyone can call your endpoint and claim they paid.
• Buy, don't build. This is the domain where rolling your own is not clever, it's negligent.

The reason payments feel scarier than they are is that they punish the exact habit web development otherwise rewards: trusting the client. Everywhere else, an optimistic UI that assumes success is good UX. Here, an optimistic UI that records success is a liability. Once you internalize that the browser can only ever say "I tried" and the server is the only thing that can say "it worked," the whole domain stops being frightening and becomes just careful — two clean lines, respected every time.

The next article stays with the values that are deceptively easy to get wrong and quietly ruin things: time and dates in React — timezones, storage, and the bugs that only surface at the worst possible hour.

If you've got a checkout that marks orders paid from a client callback, that's the second line crossed, and it's worth fixing before it costs you. Tell me how your success path works and I'll tell you where the hole is.

Ask most developers what internationalization means and you'll get the same answer: instead of writing "Save" in your JSX, you look up a key in a dictionary and get "Save" or "Enregistrer" depending on the user's language. And they're right — that is part of it. It's also the easy 10%, and it's the part that makes people underestimate the whole thing.

Because a translated string is not a translated interface. The moment you actually ship to another language, the interesting failures show up, and none of them are about the words. A date renders as 7/18/2026 to an American and 18/07/2026 to nearly everyone else. A price needs a different currency symbol, in a different position, with a comma where you had a period. "1 item" versus "5 items" is trivial in English and a genuine grammar problem in languages with six plural forms. And in Arabic or Hebrew the entire layout flips direction. None of that is a dictionary lookup.

So this article is about the 90% — what internationalizing a React app actually involves once you stop thinking of it as translation and start thinking of it as formatting and loading, which is what it really is.

The Reframe: It's Formatting, Not Words

Here's the shift that made i18n click for me. Stop picturing a dictionary. Picture a formatting engine.

The hardest parts of internationalization aren't the strings you wrote — they're the values you render. A date is a value that has to be formatted for a locale. A number is a value. A currency amount is a value. A count that decides between "item" and "items" is a value running through a locale's plural rules. The English strings are static and easy; the dynamic values are where every locale disagrees, and where a naive app quietly produces wrong output that looks fine to you and broken to them.

Translation handles the words you wrote. Internationalization handles the values you render. The second one is the hard part, and it's the part people skip.

The good news is you don't implement any of this yourself. The browser ships a full formatting engine — the Intl API — and the React libraries are wrappers that make it ergonomic.

Formatting Values the Right Way

The instinct, when you need a date or a price in the UI, is to build the string by hand — grab the month, slap it together, append a currency symbol. That instinct is exactly the bug, because the format itself is locale-dependent, not just the numbers inside it.

The Intl API already knows every locale's rules. You give it a value and a locale; it gives you correct output:

// Dates: same instant, formatted for the user's locale.
new Intl.DateTimeFormat('en-US').format(date); // "7/18/2026"
new Intl.DateTimeFormat('de-DE').format(date); // "18.7.2026"

// Currency: symbol, position, and separators all differ by locale.
new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
  .format(1234.5); // "$1,234.50"
new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' })
  .format(1234.5); // "1.234,50 €"

Look at what you're not deciding: where the currency symbol goes, whether the thousands separator is a comma or a period, the order of day and month. You hand over the value and the locale and get correct output. Building any of that by hand isn't just more code — it's code that's confidently wrong in locales you don't personally read.

Then there's pluralization, which English makes look trivial and other languages do not. "1 item" / "2 items" is a two-case rule; Polish and Arabic have far more, and a hardcoded count === 1 ? 'item' : 'items' is simply broken there. This is why the string libraries use the ICU message format, which encodes plural rules per locale:

{count, plural, one {# item} other {# items}}

You write the rule once; the library picks the right form for whatever locale is active, using the same Intl plural data. You are never in the business of knowing Polish grammar — you're in the business of not hardcoding English grammar.

The React Side: Loading, Not Bundling

Now the part that's specifically a React and architecture problem, and the one that separates a demo from a real app: you cannot ship every language in your bundle.

Here's the trap. You wire up react-i18next or FormatJS, it works, and to make it work you import all your translation files at the top. Now every user downloads English, French, German, Japanese, and Arabic just to see the one language they actually use. Your bundle balloons with text 90% of users will never read, and it gets worse with every locale you add. A feature meant to serve more users made the app slower for all of them.

The right shape is to treat translation data as something you load on demand, the same way you'd code-split a route. The active locale's messages load when needed; the rest stay on the server until someone actually switches:

// Load only the active locale's messages, not all of them.
async function loadMessages(locale: string) {
  const messages = await import(`../locales/${locale}.json`);
  return messages.default;
}

That dynamic import is the whole difference. A user on French downloads French. Switch to German and German loads then — a small, one-time fetch — instead of everyone paying for every language up front. The i18n libraries support this directly; the mistake is not the library, it's statically importing everything because the demo did.

This is the same instinct the whole series keeps returning to: the naive version loads everything eagerly, and the production version loads what's needed when it's needed. Translations are just data, and data that most users won't touch belongs behind a lazy load.

One More Thing: Direction

A short but real one, because it's the part that turns a "translated" app back into an untranslated-looking one. Some languages — Arabic, Hebrew, Persian — read right-to-left, and that's not a font setting, it's a layout inversion. Your sidebar moves to the other side, your icons mirror, your text aligns the other way.

The workable answer is to stop thinking in "left" and "right" and start thinking in "start" and "end." Modern CSS logical properties — margin-inline-start instead of margin-left, padding-inline-end instead of padding-right — flip automatically with the document direction. Set dir="rtl" on the root for RTL locales and a layout built on logical properties reorients itself. Build it on hardcoded left/right and you get to audit every component by hand. It's cheap if you do it from the start and expensive if you retrofit — which is a good reason to reach for logical properties by default even in a single-language app.

How I'd Approach It

Strip it to decisions:

• It's formatting, not translation. The strings are easy; the values — dates, numbers, currency, plurals — are where locales actually disagree.
• Never format values by hand. Use Intl (via your i18n library). It already knows every locale's rules; you never do.
• Use ICU message format for plurals. Don't hardcode English's two-case grammar into a multi-locale app.
• Load locales on demand, don't bundle them all. Dynamic-import the active language; leave the rest on the server.
• Build layout on logical properties. start/end, not left/right, so RTL is a setting and not a rewrite.

I used to think of i18n as a chore you tack on at the end — extract the strings, hand them to translators, done. That framing is why so many "internationalized" apps still show a German user an American date and an Arabic user a left-to-right layout. The strings were never the hard part. The hard part is that every locale formats values differently and reads in its own direction, and the app has to be built to bend to that instead of assuming the world works like the machine you developed on. Get the formatting and loading right and translation is the small, boring finish — which is exactly where it should sit.

Speaking of values that quietly differ everywhere and ruin your day when you get them wrong — the next article is about handling money in React: what taking a payment actually requires, and why the client should never be the thing that decides you got paid.

If you've got an app that "supports" multiple languages but still leaks the developer's locale — an English date here, a broken plural there — that's the formatting-not-translation gap. Tell me what's showing wrong and I'll point you at which piece is missing.

I've been writing code since 2003. That's over twenty years of watching patterns come and go — and occasionally making the same mistakes the patterns were supposed to prevent.

My first serious FSD project was one of those mistakes.

Feature-Sliced Design is one of the most popular frontend architectures today. The docs are clear, the community is active, the rules make sense on paper. You read through it and something clicks: pages here, features there, entities in their own layer, shared utilities at the bottom. Clean. Logical. Structured.

So I followed the rules. Meticulously.

And I ended up with a codebase where a single button — one button that validated a form field — lived across ten folders. Its logic was in features/. Its type was in entities/. Its hook was in shared/hooks/. Its analytics call was somewhere in features/analytics/. Its test was buried in __tests__/features/. To understand what that button did, you had to open half the project.

I was frustrated. For a while, I blamed myself — maybe I didn't understand FSD well enough. Maybe I was doing it wrong. It took me some time to realize: the problem wasn't the architecture. The problem was that I had stopped thinking.

The Smeared Component

There's a pattern I've started calling the smeared component. You've probably seen it. You might have built it.

It happens when a single feature — a payment form, an order widget, a settings panel — gets distributed across the project's folder structure "correctly." Each piece goes to its designated layer. Hooks go to hooks/. Types go to types/. API calls go to api/. Validators to validators/. Stories to stories/. Tests to __tests__/.

The result looks organized from the outside. Every folder has the right things in it.

But try to understand the component. Try to fix a bug in it. Try to onboard a new developer onto it. You'll open one file, realize you need another, follow an import, land in a third folder, lose track of the original file, open a fourth — and fifteen minutes later you're not sure you've seen all the pieces yet.

Code is read far more often than it is written. Architecture should optimize for understanding — not just separation.

The smeared component optimizes for separation. It's perfectly layered. And it's nearly impossible to hold in your head.

A Real Example: PaymentMethodSelector

Let me show you what this looks like in practice.

Imagine a PaymentMethodSelector component — the kind you see on checkout pages. It fetches available payment methods from an API, displays them with icons and descriptions, handles selection state, validates the selected method against order constraints, shows a modal for adding a new card, fires analytics events on selection change, and stores the result in global state.

A well-intentioned FSD implementation might distribute it like this:

src/
  features/
    payment-method/
      ui/
        PaymentMethodSelector.tsx     ← main component
        PaymentMethodOption.tsx
        AddPaymentModal.tsx
  entities/
    payment/
      model/
        payment.store.ts              ← Zustand store
        payment.selectors.ts
      api/
        payment.api.ts                ← API calls
      types/
        payment.types.ts              ← types and interfaces
  shared/
    hooks/
      usePaymentValidation.ts         ← validation logic
    analytics/
      payment.analytics.ts            ← analytics events
    lib/
      formatters/
        payment.formatters.ts         ← formatting helpers
  __tests__/
    features/
      PaymentMethodSelector.test.tsx
  stories/
    PaymentMethodSelector.stories.tsx

Eight locations. For one component.

Now imagine the validation logic needs to change — a new payment method has different constraints. You update usePaymentValidation.ts. The type needs updating — payment.types.ts. The API response shape changed — payment.api.ts. The analytics event needs a new field — payment.analytics.ts. Update the test — somewhere in __tests__/features/. Update the story. Six folders. One change.

Every bug fix is an archaeological dig. Every refactor is a leap of faith.

Here's what the same component looks like with colocation:

src/
  features/
    payment-method/
      PaymentMethodSelector.tsx
      PaymentMethodSelector.types.ts
      PaymentMethodSelector.hooks.ts
      PaymentMethodSelector.api.ts
      PaymentMethodSelector.store.ts
      PaymentMethodSelector.analytics.ts
      PaymentMethodSelector.utils.ts
      PaymentMethodSelector.test.tsx
      PaymentMethodSelector.stories.tsx
      ui/
        PaymentMethodOption.tsx
        AddPaymentModal.tsx

Everything that changes together lives together. One folder. One mental unit. One place to look.

"But FSD Doesn't Allow That"

I can already hear the objection: "FSD has rules. Types belong in entities. Hooks belong in shared. You can't just put everything in features."

Here's the thing: FSD is a tool. Not a commandment.

The methodology was designed for the common case — and the common case is a typical CRUD feature with thin logic and shared primitives. For a simple UserAvatar component, fine — put the type in entities, the API call in shared. The overhead is minimal because the component is minimal.

But for a complex, domain-rich feature like PaymentMethodSelector? The cost changes. Every "correct" placement is a navigation tax you pay every time you touch the component.

FSD actually allows adaptation. You can add a core/ layer for truly foundational cross-cutting concerns. You can extend shared/ with domain-specific subfolders. You can colocate everything within a feature when that feature is complex enough to justify it. The methodology explicitly says the structure should serve the project — not the other way around.

I've worked on a project where the team extended FSD's layer model to add a core/ layer for infrastructure-level services: logging, auth tokens, global config. Things that don't belong to any feature but are too specific for shared/. It worked cleanly. No FSD rule was violated — because the rule was never "these are the only layers you can have." The rule was "maintain the import direction and keep dependencies explicit."

Architecture is not what you do by the rules. It's how you solve the problem in front of you — in a way that stays solvable tomorrow.

Why We Keep Doing This

The reason we smear components is usually good intentions. We read the docs. We follow the patterns. We want the project to be "clean." We've been burned by messy codebases before and we never want to go back.

So we apply the architecture top to bottom, folder by folder, layer by layer. And it works. Until the project grows. Until the component gets complex. Until someone new joins and spends three days just finding where things are.

I've worked in legacy codebases where the original authors followed every rule. The folder structure is immaculate. And the cognitive load of working in it is brutal — because everything looks right but nothing reads right. Opening a component means opening a new tab for the hook, a new tab for the type, a new tab for the API call. Your brain is juggling six contexts at once.

I've been that original author too, on my first FSD project. I was so focused on placing files correctly that I stopped asking whether the placement made the code better.

What Architecture Actually Optimizes For

Good architecture optimizes for:

• Locality — related things are close to each other
• Discoverability — you can find what you're looking for without a map
• Changeability — when requirements change, the blast radius is predictable
• Cognitive simplicity — a developer can hold the relevant context in their head

Less useful to optimize for:

• Folder aesthetics
• Layer purity
• DRY at the cost of everything else

These aren't opposites. A well-applied FSD project can nail all the good ones. But "well-applied" requires judgment, not just rule-following.

The principle I keep coming back to: things that change together should live together. It sounds simple. It's not always easy to apply. But it's the right question to ask before you decide where a file goes.

A Practical Test

Before placing a file in its "architecturally correct" location, ask yourself:

1. If I need to change this file, what other files will I need to open at the same time?
2. Are those files nearby — or spread across the project?
3. If a new developer needed to understand this feature, how many folders would they need to open?

If the answers make you uncomfortable, you're probably optimizing for layer purity instead of developer experience. Reconsider the placement.

This isn't "ignore architecture." It's the opposite — it's using the architecture deliberately. FSD, done thoughtfully, is excellent. Applied mechanically — rule by rule, folder by folder, without judgment — it produces smeared components and frustrated developers.

I've worked on both kinds of projects. The difference wasn't the architecture they used. It was the thinking behind it.

Everything in this series so far has had the same conversation shape: the client asks a question, the server answers. You call useQuery, the request goes out, the response comes back. The client always speaks first. It's a comfortable model, and it's most of what a web app does.

Real-time flips the direction. Now the server speaks first — a new message lands, a price ticks, another user drags a card across the board — and your UI has to already be listening, with no request that triggered it. That inversion is the whole thing that makes real-time feel different to build, and it's where people reach for a WebSocket and immediately make the mistake that poisons the rest of the feature.

The mistake is treating the live connection as a second source of truth. You already have server state, cached and managed. Then you open a socket, start catching messages, and stuff them into a separate piece of React state. Now you have two stores that are supposed to represent the same reality, updated through two different channels, and they drift. This article is about not doing that — how I wire a live connection into the state I already have, so the app stays live and consistent.

First: Do You Even Need a WebSocket?

Before the socket, a fork in the road, because "real-time" gets reached for reflexively and WebSockets are the heaviest option.

There are really three tools, and they're not interchangeable. Polling — just refetch on an interval — is the humble one everyone forgets. If "real-time" means "within thirty seconds," a refetchInterval on an existing query is the entire feature, no new infrastructure, and you should feel no shame about it. Server-Sent Events (SSE) are a one-way stream from server to client over plain HTTP: perfect when the server needs to push but the client never pushes back — notifications, a live feed, status updates. WebSockets are the full bidirectional pipe, and you want them when both sides talk continuously: chat, collaborative editing, multiplayer anything.

The honest default is to start at the top of that list and only move down when the requirement forces it. A surprising number of "we need WebSockets" features are actually a polling interval or an SSE stream wearing a costume. Reach for the bidirectional socket when you genuinely have bidirectional, continuous communication — not before.

The Core Idea: One Source of Truth

Here's the principle that makes the rest of this easy, and it's worth stating before any code:

The live connection is a delivery mechanism, not a place to store state. Messages arrive on the socket and are handed to your existing cache. They don't get their own store.

You spent the data fetching article setting up TanStack Query as the manager of server state. Real-time doesn't replace that — it feeds it. When a WebSocket message arrives, its job isn't to become a new piece of state you render directly. Its job is to update the cache that's already the source of truth. The socket is a courier. It delivers news to the store; it isn't the store.

Get this one idea right and the two-sources-of-truth bug simply can't happen, because there's still only one source of truth. The socket just has a new way of writing to it.

Wiring a Socket Into the Cache

Concretely, there are two moves when a message arrives, and choosing between them is most of the skill.

The blunt move is invalidate: a message says "something changed over here," and you tell TanStack Query to refetch that query. You don't trust the message to carry the new data — you use it purely as a signal, and the refetch pulls fresh truth from the server.

import { useQueryClient } from '@tanstack/react-query';
import { useEffect } from 'react';

function useTicketUpdates(socket: WebSocket) {
  const queryClient = useQueryClient();

  useEffect(() => {
    function handleMessage(event: MessageEvent) {
      const msg = JSON.parse(event.data);
      if (msg.type === 'ticket.updated') {
        // The socket is just a signal. Refetch the real data.
        queryClient.invalidateQueries({ queryKey: ['tickets', msg.ticketId] });
      }
    }

    socket.addEventListener('message', handleMessage);
    return () => socket.removeEventListener('message', handleMessage);
  }, [socket, queryClient]);
}

Invalidation is safe and simple: the server stays authoritative, and you never render data the socket made up. The cost is an extra round trip per message, which is fine for low-frequency events and wrong for a firehose.

The sharp move is write the message straight into the cache with setQueryData, when the message already carries the full new value and refetching would be wasteful — a chat message, a price tick:

function handleMessage(event: MessageEvent) {
  const msg = JSON.parse(event.data);
  if (msg.type === 'chat.message') {
    queryClient.setQueryData(['chat', msg.roomId], (old: Message[] = []) => [
      ...old,
      msg.message,
    ]);
  }
}

Same principle either way — the socket updates the one cache — but setQueryData skips the round trip by trusting the payload. My rule of thumb: invalidate for "something changed," write directly for "here is exactly what changed." High-frequency streams where a refetch-per-message would melt your server are the clear case for writing directly; everything else, start with invalidate because it's harder to get wrong.

The Part Everyone Underestimates: The Connection Lifecycle

Opening a socket is the easy 20% again. The other 80% is that connections are not reliable, and a real-time feature is only as good as how it handles a connection that isn't there.

The network drops. The laptop sleeps and wakes. A deploy restarts the server and every socket dies at once. If your feature assumes a persistent, healthy connection, it silently stops updating and the user has no idea — which is worse than a visible error, because they're now looking at stale data they believe is live. So the lifecycle work is not optional polish; it's the feature. You need reconnection with backoff so a blip heals itself instead of ending the session. You need to resync on reconnect — when the socket comes back, invalidate the relevant queries and refetch, because you almost certainly missed messages while it was down, and the socket can't replay history it never delivered. And you owe the user connection status in the UI, even something quiet, so "live" and "trying to reconnect" don't look identical.

This is exactly why not hand-rolling the raw WebSocket for anything serious is the right call. A library like Socket.IO exists to handle reconnection, fallbacks, and connection state for you — the same trade as every other article in this series, where the value isn't the raw capability but the library that manages its messy edges. Raw WebSocket is fine to learn on and fine for a toy. For a feature people depend on, let something else own the reconnection logic, and spend your attention on what the messages mean.

How I'd Approach It

Strip it to decisions:

• Don't reach for WebSockets reflexively. Polling and SSE cover more cases than people admit. Use the bidirectional socket only for genuinely bidirectional, continuous features.
• The connection is a courier, not a store. One source of truth stays your TanStack Query cache; the socket writes to it.
• Invalidate for "something changed," setQueryData for "here's exactly what changed." Start with invalidate; reach for direct writes when the frequency demands it.
• The lifecycle is the feature. Reconnect with backoff, resync on reconnect, show connection status. A silently dead socket is worse than an error.
• Let a library own the connection. Hand-rolled raw sockets are for learning, not for things people rely on.

The thing that used to make real-time feel hard, for me, was imagining it as a whole separate system bolted onto the app — its own state, its own rules, its own bugs. It isn't. It's one new way for data to arrive into the store you already have. Once the socket stops being a source of truth and becomes a courier delivering to your cache, the "two states that disagree" class of bug disappears, and what's left is just careful handling of a connection that can drop. That part takes discipline, but it's a known problem with known answers.

Next up, a different kind of "the same app, but harder": internationalization in React — which turns out to be far less about translating strings and far more about formatting, loading, and everything that quietly breaks when your app leaves one language.

If you've got a real-time feature where the UI occasionally shows stale data or two views disagree, that's almost always a two-sources-of-truth problem or a missed-resync-on-reconnect problem. Tell me the symptom and I'll tell you which.

The first AI demo you build feels like cheating. A text input, a fetch to a model, a response on screen — thirty lines, maybe less, and suddenly your app talks. It's genuinely exciting, and that excitement is exactly the trap. Because the demo is the easy 20%. The moment you try to put that chat box in front of real users, the other 80% arrives all at once, and none of it is about the model.

The response doesn't appear all at once — it streams, token by token, and your UI has to handle that gracefully. You don't just want text back, you want structured data you can render into a component, and the model doesn't always cooperate. The request takes seconds, sometimes fails halfway, and your app has to stay honest about loading and error states the whole time. This is the part the demos skip, and it's the entire job.

So this article isn't "how to call an LLM." Calling the model is trivial. This is about the React-side reality of turning that call into something you'd actually ship — the streaming, the structure, the state — and where the current tools genuinely help versus where you're still on your own.

Why AI Broke My Normal Data Layer

Up to this point in the series, every data problem had the same shape. You fire a request, you wait, you get a response, TanStack Query caches it and hands it to your component. Request, response, done. It's a clean model and it covers almost everything.

AI breaks it in one specific way: the response isn't a single event, it's a stream. The model produces its answer incrementally, and the whole point — the thing that makes it feel alive — is showing those tokens as they arrive. A spinner that sits for eight seconds and then dumps a wall of text feels broken, even when it's technically correct. The perceived quality of an AI feature is almost entirely about the streaming.

That's a different primitive than request/response. You're not awaiting a value; you're consuming a sequence over time and rendering each chunk. Trying to force that into a normal useQuery fights the grain of the tool. This is why AI-specific React libraries exist — not because calling a model is hard, but because streaming a model's output into a UI is a genuinely different problem, and doing it by hand means manually managing readers, buffers, partial state, and cancellation.

The Streaming Chat, Handled For You

The good news is that this exact problem is now well-solved. The Vercel AI SDK (and the TanStack-flavored patterns around it) exists precisely to make streaming chat a solved problem on the React side. Its useChat hook is the useQuery of this world — it owns the messy part so you don't.

import { useChat } from 'ai/react';

export function SupportChat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } =
    useChat({ api: '/api/chat' });

  return (
    <div className="support-chat">
      {messages.map((m) => (
        <div key={m.id} data-role={m.role}>
          {m.content}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} disabled={isLoading} />
        <button type="submit" disabled={isLoading}>Send</button>
      </form>
    </div>
  );
}

Look at what you didn't write. No stream reader. No manual buffering of partial tokens. No hand-rolled "append this chunk to the last message" logic. messages updates as tokens arrive, so the response types itself onto the screen. isLoading gives you the state to disable the input and show activity. The entire streaming problem — the thing that would take a day to get right by hand and stay subtly buggy — is inside the hook.

This is the same lesson as every other article in this series: the value isn't the raw capability, it's a library that takes the awkward part and gives you a clean React interface for it. useChat is to streaming what TanStack Query is to caching.

The Part That Actually Trips People Up: Structured Output

Streaming text is solved. Here's where it gets real: most of the time you don't want a paragraph of prose, you want data. You want the model to extract three fields from an invoice, or classify a support ticket, or return a list of suggested tags — and then you want to render that into an actual component, not a string.

The naive approach is to ask the model for JSON in the prompt and JSON.parse the result. Do this in a demo and it works. Do it in production and it breaks, because the model is a text generator, not an API. Sometimes it wraps the JSON in ````json fences. Sometimes it adds a friendly "Sure, here's the data:" preamble. Sometimes it hallucinates a field. JSON.parse throws, and now your feature is down because the model was chatty.

The current answer is to stop hoping and start enforcing. You define a Zod schema for the shape you need and let the SDK constrain the model to it:

import { generateObject } from 'ai';
import { z } from 'zod';

const ticketSchema = z.object({
  category: z.enum(['billing', 'technical', 'account', 'other']),
  priority: z.enum(['low', 'medium', 'high']),
  summary: z.string(),
});

const { object } = await generateObject({
  model,
  schema: ticketSchema,
  prompt: `Classify this support ticket: ${ticketText}`,
});

// object is typed as { category: ..., priority: ..., summary: string }
// and validated — not a hopeful JSON.parse.

The difference is the difference between a demo and a product. object isn't a string you're praying parses — it's a validated, typed value the SDK guarantees matches your schema, or the call fails loudly instead of feeding garbage into your UI. Notice this is the exact same Zod schema pattern from the forms article, pointed at a new problem. You already know this tool. The model becomes just another untrusted input source you validate at the boundary — which, if you've read the authentication piece, is exactly how you should treat everything crossing into your app.

Treat model output like user input, not like an API response. It is text that happens to look structured. Validate it, or it will embarrass you in production.

Where the Tools Stop and You Start

I want to be honest about the edges, because the ecosystem is young and the demos oversell.

The streaming and structured-output tools are solid. What they don't solve is everything around the call. Cost — every token is money, and a chat feature with no limits is a bill waiting to happen; you need throttling and usage caps, and those are your problem, not the SDK's. Latency — responses take seconds, and no amount of UI polish makes a slow model fast; you design around the wait, you don't remove it. Failure — models time out, hit rate limits, and return nonsense, so every AI feature needs the same error handling discipline as any other flaky network dependency, plus a graceful answer for "the model gave me something useless."

And the honest constraint underneath all of it: the model is non-deterministic. The same input can produce different output. That breaks a core assumption every other part of your app relies on. You can't snapshot-test it the normal way, you can't guarantee a given response, and you have to design UI that stays usable when the answer is wrong. That's not a library gap that'll be patched next quarter. That's the nature of the thing, and building AI features well means designing for it rather than pretending it away.

How I'd Actually Approach It

Strip it to decisions:

• Streaming is the product, not a detail. The feel of an AI feature is the streaming. Don't fake it with a spinner.
• Don't hand-roll the stream. Use useChat / the AI SDK. It's the useQuery of streaming — it owns the messy part.
• Never trust free-form JSON. Use generateObject with a Zod schema. Treat model output as untrusted input, validated at the boundary.
• Budget for cost, latency, and failure from day one. They're your responsibility, not the SDK's, and they don't go away.
• Design for non-determinism. The answer can be wrong. The UI has to survive that.

The demos make AI look like a feature you drop in. It isn't. It's a new kind of data source — streaming, untrusted, non-deterministic, and metered — and the work is treating it with the same engineering seriousness you'd give any other unreliable dependency. The tools have gotten genuinely good at the streaming and the structure. The judgment — where to use it, how to fail, what to guarantee — is still entirely yours, and that's the part worth getting right.

The next article stays in real-time territory but drops the AI: WebSockets and real-time in React — how to keep a UI live when the server has something to say, and how it fits with the TanStack Query cache you already have.

If you're building an AI feature and it works beautifully in the demo but falls apart with real traffic, that gap is almost always one of these — streaming, structure, or the metered/non-deterministic reality underneath. Tell me where it breaks and I'll tell you which one it is.

Two developers look at the same untested codebase and reach opposite conclusions. One says "this is reckless, we need 100% coverage before we ship anything else." The other says "tests are why we're slow, they break every time we change a line, let's just be careful instead." I've been in rooms with both, and here's the uncomfortable thing: they're both partly right, and both are optimizing the wrong variable.

Because a test isn't a virtue and it isn't a tax. It's a trade — effort and speed now, in exchange for confidence and safety later. Some of those trades are wildly worth it. Some cost more than they'll ever return. The whole skill of testing isn't writing tests; it's knowing which trade you're making and whether it pays off.

So this article isn't a testing tutorial and it definitely isn't a coverage sermon. It's how I actually decide what to test in a React app, so I end up with a suite that catches real bugs without becoming the brittle, resented thing that everyone works around.

The Pain Each Kind of Test Removes

Forget the pyramid diagram for a second. The useful question isn't "what are the types of tests," it's "what specific pain does each one remove." Because if a test isn't removing pain, you're paying for nothing.

Unit tests remove the pain of a single piece of logic being subtly wrong. A pricing calculation, a date formatter, a reducer with tricky edge cases. Fast, focused, and they pin down the exact spot a bug lives.

Component tests remove the pain of a UI piece behaving wrong when a user touches it. Does the form show the error, does the button disable while submitting, does the list render what it's handed. This is where most React testing value actually lives, and we'll spend the most time here.

End-to-end (E2E) tests remove the pain of the whole thing being broken even though every piece works alone. The classic disaster: every unit passes, and login is still broken because two correct parts don't fit together. E2E drives a real browser through a real flow and catches exactly that.

Each targets a different fear. Unit: "is this logic right?" Component: "does this behave when used?" E2E: "does the actual journey work?" You don't need all three everywhere. You need each one where its specific fear is real.

The One Rule That Fixed My Component Tests

For a long time my React tests were brittle. I'd change an implementation detail — rename a state variable, restructure a handler, swap a class name — and a dozen tests would go red without a single actual bug. That's the experience that makes people hate testing, and it turns out it was my fault, not testing's.

The rule that fixed it: test behavior, not implementation. Test what the user experiences, not how the component achieves it.

React Testing Library is built entirely around this idea, and once it clicked, my tests stopped breaking for stupid reasons. You don't query for internal state or component instances. You query the DOM the way a user perceives it — by text, by role, by label — and you interact the way a user does.

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('shows an error when submitting an empty policy holder name', async () => {
  render(<PolicyForm />);

  // Interact like a user: find the button by its accessible role.
  await userEvent.click(screen.getByRole('button', { name: /save/i }));

  // Assert on what the user actually sees.
  expect(screen.getByText(/holder name is required/i)).toBeInTheDocument();
});

Look at what that test doesn't know. It doesn't know if PolicyForm uses useState or a form library, whether the error lives in local state or context, what the handler is called. I can rewrite the entire internals of that component and, as long as an empty submit still shows that error, the test stays green. That's the point: the test is coupled to the behavior the user relies on, not the code I happened to write. Implementation-coupled tests break when you refactor; behavior-coupled tests break when you regress. Only one of those is useful.

This connects straight back to the forms article: the reason I could confidently recommend a specific form library is that behavior tests let me swap implementations without rewriting the test suite. Good tests make good architecture decisions cheaper to reverse.

Vitest, Quickly

A note on tooling, because it changed and the old advice lingers. For years Jest was the default. Today, for a Vite-based app — which is most new React apps — Vitest is the natural pick. It reuses your existing Vite config and transforms, so there's no separate parallel build setup to maintain, and it's fast. The API is close enough to Jest that everything you know transfers. Pair it with React Testing Library and you have the whole component-testing stack. I won't belabor it: if you're on Vite, use Vitest, and move on to the part that matters, which is deciding what to test.

What I Actually Test, and What I Don't

Here's where the "it's a trade" framing turns into decisions. Not everything deserves a test, and pretending otherwise is how you get a slow, resented suite.

I test the things that are painful when wrong. Business logic with real consequences — pricing, permissions, anything money- or data-integrity-related. Complex conditional UI, the kind with enough branches that I can't hold them in my head. Bugs I've already fixed once, which get a regression test so they can't come back. Custom hooks with real logic. These earn their keep because the cost of them silently breaking is high.

I don't test the things that are cheap to verify by looking. A component that renders a prop into a heading. Trivial passthrough. Third-party libraries — that's their job, not mine. Static markup with no logic. Writing a test for <h1>{title}</h1> doesn't remove any pain; it just adds a file that has to change every time the markup does.

The honest heuristic I use: before writing a test, I ask what bug it would catch and how bad that bug would be. If I can't name a realistic bug, or the bug would be obvious and harmless, I skip it. If the bug would be subtle, expensive, or embarrassing, I write the test first. Coverage percentage never enters the decision — a codebase at 100% coverage full of <h1> tests is worse than one at 60% that covers every pricing path, because the first one is mostly noise you have to maintain.

Coverage measures how much code ran during tests. It says nothing about whether the tests would catch a bug that matters. Chasing the number optimizes the wrong thing.

E2E: A Little Goes a Long Way

End-to-end tests are the most expensive to write and maintain and the slowest to run, so I'm deliberately stingy with them — but the few I keep are the ones I'd least want to live without.

I don't E2E every screen. I E2E the handful of flows where "broken and nobody noticed" would be a genuine disaster: the signup and login path, the checkout or core conversion flow, the one or two journeys the business actually runs on. Tools like Playwright drive a real browser through those, catching the integration failures that unit and component tests structurally can't see.

import { test, expect } from '@playwright/test';

test('a user can sign in and reach the dashboard', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('correct-horse');
  await page.getByRole('button', { name: /sign in/i }).click();

  await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible();
});

Notice it's the same philosophy as the component test — interact by role and label, assert on what the user sees — just scaled up to the whole journey through a real browser. A small number of these, guarding the flows that matter most, buys an enormous amount of confidence for the cost. Try to E2E everything and you get a slow, flaky suite people disable. Guard the critical few and you get a safety net people trust.

How This All Fits Together

Strip it to decisions:

• A test is a trade, not a virtue. Effort now for confidence later — only worth it when the confidence is worth more than the effort.
• Match the test to the fear. Unit for logic, component for behavior, E2E for the critical journey.
• Test behavior, not implementation. Query and interact like a user, so refactors don't turn your suite red for no reason.
• On Vite, use Vitest with React Testing Library, and stop thinking about tooling.
• Ask "what bug would this catch, and how bad is it?" before writing any test. Skip the ones with no honest answer.
• Ignore the coverage number. Cover what hurts when it breaks.

I used to think the goal of testing was a high coverage number, and I wrote a lot of useless tests chasing it. The goal is confidence — the specific, earned feeling that you can change this code and not break something that matters. A suite that gives you that at 60% honest coverage is worth more than one that gives you false comfort at 100%. Tests aren't there to make a dashboard green. They're there so you can move fast without being afraid, and every test that doesn't serve that is just weight you're carrying.

This is the last piece of the "build a complete app" arc — start a project, structure it, fetch data, route, manage state, style, build forms and charts, authenticate, talk to a backend, render on the server, store data, deploy, and now test it. From here the series turns to the sharper edges: the next article is about React and AI — what the current tools actually make possible in a real app, past the demos.

If you've got a test suite that everyone quietly works around — slow, brittle, red for the wrong reasons — that's usually a "testing implementation instead of behavior" problem, and it's fixable. Tell me what breaks when you refactor, and I'll tell you what I'd change.

The first time I deployed something to production, it took a week and a person whose entire job was making deployments happen. There was a server to configure, a pipeline to wire, environment variables to get wrong in six interesting ways, and a deploy checklist that read like a pre-flight sequence. Shipping was an event.

The last thing I deployed took a git push. No server, no pipeline I wrote, no checklist. I pushed to main, and a minute later it was live with a URL and HTTPS I didn't configure. Same person, same nervousness the first time — and almost none of the work.

That compression is the story of modern hosting, and it's easy to take for granted until you realize it quietly changed who gets to ship things. When deployment stops being a discipline, a single developer can put a real, full-stack app in front of real users without a DevOps team standing behind them. So this article is about how to think about hosting a React app now — not a tutorial for one platform, but the mental model, the tiers, and the place where the magic politely stops.

First, What Are You Actually Deploying?

The most common hosting confusion isn't about platforms. It's that "deploy my React app" means two completely different things depending on what you built, and picking the wrong kind of host is where people get stuck.

A static site. If your app is client-side rendered or statically generated — this very blog is a static export — then "deploying" is just serving files. HTML, CSS, JS, sitting on a CDN. There's no server running your code; there's a very fast file server near your users. This is the cheapest, simplest, most durable thing you can ship, and platforms like GitHub Pages, Netlify, Cloudflare Pages, and Vercel do it beautifully, often free.

An app with a server. The moment you have SSR, server functions, or a backend and database, there's actual code that has to run on demand, somewhere, all the time. That's not a file server. That's a running process, and it needs a host that keeps it alive, scales it, and gives it access to your database.

Almost every hosting mistake I see is someone trying to fit one of these into the other's home — pushing a full-stack app onto a static-only host and wondering why the server code never runs, or paying for an always-on server to deliver what is really just a folder of files. Know which one you have first. Everything else follows from that.

The Static Path: Basically Solved

If you're shipping a static site, the good news is you barely have to think. Connect your Git repo to Netlify, Cloudflare Pages, Vercel, or GitHub Pages; every push to your main branch builds and deploys automatically; you get a global CDN, HTTPS, and preview URLs for pull requests without configuring any of it.

This series' own site is the proof — a Next.js static export pushed to a branch, built by CI, served from a CDN, on a custom domain. There is no server. There is nothing to keep running. And that's exactly why it's the most robust option: the thing that can't crash at 3am is the thing that isn't running. If your app can be static, let it be static, and enjoy how little there is to worry about.

The Full-Stack Path: Where Railway Comes In

The interesting decisions start when you have a server to run. Now you need a platform that takes your code, containerizes it, keeps the process alive, connects it to a database, manages environment variables and secrets, and scales it when traffic climbs — all without you learning Kubernetes.

This is the category Railway lives in, alongside Render, Fly.io, and the more serverless-shaped Vercel functions model. What they share is the same compression that hit static hosting, now applied to running servers: you connect a repo, and a git push builds and deploys a live process.

# The entire "deploy a full-stack app" story, conceptually:
git push            # push to the connected branch
# platform detects the app, builds a container,
# injects env vars, runs it, gives it a URL and HTTPS

What I like about this generation of platforms is that they collapse the app and its dependencies into one place. On Railway you can provision your database right next to your app and wire them together in the dashboard, so the Turso-or-Postgres decision from the last article and the hosting decision stop being two separate projects. The whole backend — process, database, environment — lives in one connected picture instead of a pile of services you glued together by hand. For a solo developer or a small team, that consolidation is the actual product.

I'm not going to crown one winner. Railway is excellent for full-stack apps that want a database and a server in one tidy place; Fly.io leans toward running close to users at the edge; Vercel is the smoothest possible home for a Next.js app specifically. The right pick depends on your stack, and the honest advice is to match the platform to the shape of what you built, not to the loudest brand.

Environment Variables: The One Thing to Get Right

If there's a single operational skill that separates a smooth deploy from a painful one, it's handling configuration correctly — and it's where security quietly rides along.

The rule is simple and non-negotiable: secrets go in the platform's environment variables, never in your code, never in your repo. Your database URL, your auth tokens, your API keys — those live in Railway's (or whoever's) settings, injected into the process at runtime.

And there's a React-specific trap worth calling out, because it burns people. Anything your frontend bundle can read is public — it ships to the browser, where anyone can open it and look. Frameworks make this explicit with prefixes: a variable exposed to the client is deliberately marked as such.

# Safe on the server only — never reaches the browser:
DATABASE_URL=...
AUTH_SECRET=...

# Deliberately public — bundled into the client, so treat as visible:
NEXT_PUBLIC_ANALYTICS_ID=...
VITE_PUBLIC_APP_URL=...

That prefix is a security boundary, not a naming convention. A secret with a public prefix is a secret you've published. This connects straight back to the authentication article: the same discipline of knowing what the browser can and cannot see applies to every environment variable you set. Get this one habit right and you've avoided the most common way small teams leak credentials.

Where the Magic Stops

I've spent this article celebrating how easy hosting got, so let me be honest about where the smooth part ends, because pretending it doesn't is how people get surprised.

Auto-scaling is real, but it isn't free or infinite — traffic spikes cost money, and a runaway process or a bad loop can run up a bill while you sleep. Cold starts are real on serverless tiers: a function that hasn't run in a while takes a beat to wake, and for some apps that latency matters. Databases have connection limits that serverless functions, which spin up many instances, can exhaust in ways that surprise you. And "it deployed" is not "it works" — you still own monitoring, logging, and knowing when production is unhappy.

None of this brings back the week-long deploy. It just means the modern platform moved your attention from how do I ship this to how does this behave once it's shipped, which is a much better problem to have. The floor got higher. The ceiling is still yours to worry about.

The Takeaway

Boil it down:

• Know what you're deploying. Static site or running server — that single fact chooses your host.
• If it can be static, let it be static. The cheapest, most durable option is the one with nothing running.
• For full-stack, use a platform that consolidates app and database. Railway, Render, Fly.io — a git push to a live process, database next door.
• Secrets in env vars, and respect the public prefix. It's a security boundary, not a style choice.
• The magic stops at runtime behavior. Scaling cost, cold starts, connection limits, monitoring — still yours.

I started this series' thread on infrastructure by admitting the database used to scare me. Hosting used to scare me for the same reason — it looked like a separate profession guarding the door to production. It isn't anymore. The tools compressed a week of DevOps into a git push, and that didn't just save time; it moved the power to ship real software into the hands of individual developers. You can build the app, store its data, and put it in front of the world, alone, in an afternoon. That's genuinely new, and it's worth not taking for granted.

The app is built, stored, and deployed. Now we make sure it stays working — the next article is about testing in React: the kinds of tests, the pain each one actually removes, and how to test without drowning in brittle suites.

If you've got an app that's stuck at the "how do I actually put this online" step, that used to be a wall and now it's a git push — tell me what you built and I'll point you at where it should live.

There's a specific fear a lot of frontend developers have, and I had it too: the database is where I'm not supposed to go. Tables, indexes, connection pools, migrations, the DBA who guards it all — it reads like someone else's territory, and the safe move is to stay in the browser where I belong.

That fear made sense a decade ago. It doesn't anymore, and holding onto it now quietly caps what you can build alone. Because "add a database" used to be a genuinely heavy sentence — provision a server, keep it running, manage a pool of connections, hand-run migrations, worry about it at 3am. Serverless rewrote every clause of that sentence, and most of the weight is just gone.

So this article is the database explainer I wish someone had handed me when I still thought data storage was off-limits. Not how to be a DBA — how to be a React developer who can pick a database, reason about it, and ship a full app without asking permission.

The Fear Was Really About Operations

Here's the thing I got wrong for years: my fear of databases wasn't about SQL. SQL is learnable in a weekend. It was about operations — the running, scaling, backing-up, not-losing-everyone's-data part. That's the genuinely hard, genuinely scary part, and it's exactly the part serverless takes off your plate.

A serverless database is one you don't run. No server to provision, no connection pool to babysit, no capacity to plan. It scales when you're busy, costs almost nothing when you're idle, and someone else owns the 3am pager. What's left for you is the part that was never scary: describing your data and querying it.

Once I understood that the wall was operational, not intellectual, databases stopped being forbidden and started being just another tool I could reach for. That reframe is the whole point of this article.

The Types, Quickly and Honestly

You need a rough map before names mean anything. There are more categories than this, but for building a React app, three matter.

Relational (SQL) — Postgres, MySQL, SQLite. Data in tables with defined relationships. This is the default, and it should be. It's proven, it's flexible, and the guarantees are strong. When you don't have a specific reason to pick something else, pick this.

Document (NoSQL) — MongoDB, Firestore. Data as flexible JSON-ish documents, no rigid schema up front. Genuinely useful when your data is loosely structured or you're moving fast before the shape settles. My honest take: teams reach for it to "avoid schemas" and later discover the schema didn't disappear, it just moved into their application code where the database can't help enforce it.

Key-value — Redis. Dead-simple pairs, blazing fast, usually a complement to a real database for caching and sessions, not your source of truth.

If you're building a typical app and unsure, the boring answer is right: a relational database. The interesting question in 2026 isn't SQL versus NoSQL — it's what serverless did to the relational option.

Why SQLite Came Back

For years SQLite was filed under "the little embedded database" — great for a phone app or a local file, not something you'd run a real web product on. That mental filing is now out of date, and it's worth understanding why, because it's the shift this whole article turns on.

SQLite is spectacularly simple and fast — the entire database is a file. What it historically lacked was a way to be that simple and live in the cloud serving a distributed app. That's the gap platforms like Turso fill: SQLite's simplicity, rebuilt for the edge, replicated close to your users, with the operational weight removed.

import { createClient } from '@libsql/client';

const db = createClient({
  url: process.env.DATABASE_URL!,
  authToken: process.env.DATABASE_AUTH_TOKEN,
});

// This is the whole "connect to your production database" story.
const policies = await db.execute('SELECT * FROM policies WHERE user_id = ?', [userId]);

Look at what isn't there. No pool configuration, no connection lifecycle, no server to have provisioned first. A URL and a token, and you're talking to a replicated production database. The thing that scared me — the operations — has been compressed into two environment variables. That's the serverless shift made concrete.

I'm not claiming Turso is the only right answer; serverless Postgres options like Neon do the same trick for the Postgres world, and if your heart is set on Postgres, reach for one of those instead. The point isn't the specific vendor. It's that the operational barrier that made databases feel off-limits has genuinely fallen, whichever ecosystem you pick.

Don't Write SQL Strings by Hand — Use an ORM

The one place I'll push you toward a specific practice: put a typed query layer between your React-adjacent code and the raw database. In the TypeScript world that means an ORM like Drizzle or Prisma, and the reason is the same thread running through this entire series — types.

Raw SQL strings are stringly-typed. A typo in a column name is a runtime error you find in production. A typed ORM turns that into a compile error you find while typing.

import { drizzle } from 'drizzle-orm/libsql';
import { eq } from 'drizzle-orm';

const db = drizzle(client);

// Fully typed: 'policies.userId' is checked, the result is typed,
// a renamed column breaks the build, not production.
const rows = await db.select().from(policies).where(eq(policies.userId, userId));
//    ^? Policy[] — inferred from the schema

This should feel deeply familiar by now. It's the exact move from the tRPC and server-functions articles: define the shape once, let the compiler carry it everywhere. Your database schema becomes a TypeScript source of truth, the same types flow from the table into your query into your TanStack Query cache and finally into your component. One definition, enforced end to end, from the database row to the rendered pixel. That's the coherence this series keeps chasing, now extended all the way down to storage.

Migrations Aren't Scary Either

The last piece of the old fear: migrations — changing your schema without breaking the running app. This used to be hand-written SQL run carefully against production, and it's where "I might delete everything" lives.

Modern ORMs largely defuse it. You change your schema definition in TypeScript, and the tool generates the migration for you.

# Change the schema in code, then:
npx drizzle-kit generate   # generates the migration from the diff
npx drizzle-kit migrate    # applies it

You still have to think — a migration that drops a column is still destructive, and no tool saves you from a bad decision. But the mechanical, error-prone part of hand-writing schema changes is handled, and the migration lives in your repo as a reviewable, version-controlled file instead of a command someone typed into a production shell and forgot.

What a React Developer Should Actually Take Away

Strip it down:

• The wall was operational, not intellectual. Serverless removed the running-and-scaling part that was actually hard.
• Default to relational. Reach for document or key-value only when you have a specific reason.
• SQLite is a real option now. Turso (or serverless Postgres like Neon) gives you production data storage behind a URL and a token.
• Use a typed ORM. Drizzle or Prisma make your schema a TypeScript source of truth, and the types flow all the way to your components.
• Migrations are generated, not hand-written — but you still own the judgment.

I spent too long treating the database as someone else's job, and all it did was make me dependent on someone else to ship anything real. The serverless shift didn't just make databases easier — it made them mine, and yours. You don't need a DBA and a provisioning ticket to store data anymore. You need a schema, a typed client, and the willingness to walk through a wall that isn't there. That, more than any single tool, is what changed.

With storage handled, the app needs to actually run somewhere the world can reach it. The next article is about hosting a React app — how modern platforms turned deployment from a DevOps project into a git push, and where the limits still bite.

If you're sitting on an app idea and the database is the part that's stopping you, that's the exact fear I'm describing — tell me what you're trying to store and I'll help you pick where it goes.

For most of this series I've drawn a clean line: React runs in the browser, the backend runs on a server, and the contract between them is where the interesting decisions live. That line is useful. It's also about to dissolve.

Server-side rendering is usually sold as a performance trick — render HTML on the server so the first paint is faster and Google can read your page. That's true, and it's the least interesting thing about it. The real change is architectural: SSR takes the wall between "frontend" and "backend" and turns it into a seam inside a single framework. Suddenly some of your React code runs on a server, some runs in a browser, and the hardest part is knowing which is which — and why it matters.

So this article isn't a list of SSR benefits. It's about what actually shifts in how you think when rendering moves to the server, and where TanStack Start lands in a world Next.js has owned for years.

What SSR Actually Buys You

Let me be fair to the standard pitch first, because the benefits are real. Server rendering gives you a faster first contentful paint — the user sees content before a single kilobyte of JavaScript executes. It gives you SEO that actually works, because crawlers get real HTML instead of an empty <div id="root">. And it gives you a better story on slow devices, because the server does the heavy lifting once instead of every phone doing it again.

If that were all SSR did, it'd be a performance optimization you turn on and forget. But turning it on changes the shape of your code, and that's the part nobody warns you about until you hit it.

The Line Moves, and You Have to Know Where

Here's the thing that trips everyone up, and it's worth slowing down on.

In a pure client-side app, all your code runs in one place: the browser. window exists. localStorage exists. Every component runs after the user's device has loaded it. Simple mental model.

The moment you add SSR, your components can run in two environments — once on the server to produce the initial HTML, and again (or partially) in the browser to make it interactive. And the server doesn't have window. It doesn't have localStorage. Code that assumed the browser now runs somewhere the browser's globals don't exist.

function Sidebar() {
  // Runs on the server first — where 'window' is undefined.
  // This throws during SSR, and the error is confusing the first time.
  const collapsed = window.localStorage.getItem('sidebar-collapsed');
  return collapsed ? <Collapsed /> : <Expanded />;
}

That crashes on the server, and the first time it happens the error message sends you on a goose chase, because it's failing in a place you didn't know your component ran. This is the tax of SSR: you now have to know, for every piece of code, where it executes. Browser-only work — reading localStorage, touching the DOM, using window — has to be deferred to after hydration, usually in an effect. It's not hard once you have the mental model. It's brutal before you do.

With SSR, "where does this run?" stops being a trivia question and becomes the question. Half of SSR debugging is just answering it correctly.

That's the real cost, and no framework fully removes it — it's inherent to running the same code in two places. What a good framework does is make the boundary visible instead of something you discover by crashing.

Hydration: The Weird Middle Step

There's a moment between "server sent HTML" and "app is interactive" that deserves a name, because it's the source of the strangest SSR bugs: hydration.

The server sends fully-formed HTML so the user sees content immediately. But that HTML is inert — no event handlers, no state. Then the JavaScript loads and React "hydrates" it: it walks the server-rendered DOM and attaches all the interactivity, expecting the DOM it finds to match the DOM it would have rendered.

When those two don't match — because you rendered a timestamp, or a random value, or something that read window — you get a hydration mismatch, and React complains. The fix is conceptual, not mechanical: anything that differs between server and client has to wait until after hydration. Once you internalize that server and client must agree on the first render, the whole class of hydration bugs stops being mysterious and starts being obvious.

Where TanStack Start Comes In

Everything so far is true of any SSR framework. So why TanStack Start, in a world where Next.js is the default answer?

Because of what this series has already built. If you've been following along, you're using TanStack Query for server state and TanStack Router for type-safe routing. TanStack Start is a full-stack framework built on that same router — so SSR, server functions, and data loading arrive as a natural extension of tools you already use, not a new paradigm you adopt wholesale.

The piece that matters most is server functions — typed functions you write once and call from the client, where the network boundary between them is handled for you.

import { createServerFn } from '@tanstack/start';

const getPolicy = createServerFn('GET', async (id: number) => {
  // This body runs ONLY on the server — DB access is safe here.
  return db.policy.findUnique({ where: { id } });
});

// Called from a component; the type flows across the boundary,
// and 'db' never ships to the browser.
const policy = await getPolicy(42);
//    ^? Policy — inferred end to end

If that feels familiar, it should — it's the tRPC idea from the backend article, folded directly into the framework. You write a function that runs on the server, call it from the client with full type safety, and the framework draws the network line for you. The db import never reaches the browser. The type reaches everything. That coherence — one router, one type system, server and client speaking the same language — is the reason Start fits this series so naturally.

The Honest Comparison with Next.js

I'm not going to pretend TanStack Start dethrones Next.js. It doesn't, and picking it over Next.js is a real trade-off, not a free upgrade.

Next.js is mature, enormous, and battle-tested at every scale, with the deepest ecosystem in React and a hosting story that's effectively frictionless on Vercel. Its App Router and React Server Components are a genuinely different, powerful model. If your team wants the safest, most-documented, most-hireable-for choice, Next.js is it, and I'd never argue someone out of it on the merits.

What TanStack Start offers is a different center of gravity. It's router-first and type-obsessed, and if your app is already built on TanStack's pieces, Start is the option where everything agrees — the same router types flow from your routes into your loaders into your server functions with no seams. Next.js asks you to adopt its model of the world; Start extends the model you already chose. For the kind of deeply-typed, client-rich application this series keeps building, that consistency is worth a lot. For a content site that wants RSC and edge rendering out of the box, Next.js is probably still the sharper tool.

That's the honest split: Next.js for maturity and reach, Start for coherence with a TanStack-native stack. Neither is a mistake.

The Real Takeaway

Strip away the framework names and here's what SSR actually asks of you:

• Know where every piece of code runs. Server or browser is now a question you answer constantly, not never.
• Defer browser-only work past hydration. window, localStorage, the DOM — none of it exists during the server render.
• Make server and client agree on the first render. Mismatches are the price of getting this wrong.
• Let the framework draw the boundary. Server functions turn "which side does this run on" from a guess into a typed contract.

I opened by saying the line between frontend and backend was about to dissolve, and this is what I meant. SSR doesn't move your code to the server — it makes "the server" and "the browser" two places your same code lives, and the skill it demands is holding both in your head at once. That's harder than it sounds and more valuable than it looks. The developers I trust most with a large React app aren't the ones who memorized a framework. They're the ones who always know where their code is running.

With rendering settled, the app needs somewhere to keep its data. The next article is about databases for React developers — the kinds, the trade-offs, and why the modern serverless options change what "add a database" even means.

If you've fought a hydration mismatch that made no sense, or you're weighing Start against Next.js for a real project, I'd like to hear the specifics — those decisions are all about your exact stack, and that's where the interesting part lives.

"That's a backend concern" is one of the most expensive sentences a frontend developer can say.

I understand the instinct. There's a clean line in most people's heads: the backend team owns the server, we own the browser, and the API is the wall between us. Someone hands you an endpoint, you fetch from it, you render. Not your problem what happens on the other side.

Except the shape of that wall decides how much of your job is real work versus glue code. I've spent weeks of my life writing frontend that existed only to paper over an awkward API — flattening nested responses, stitching three calls into one screen, re-deriving fields the server could have just sent. That's not frontend work. That's tax, paid in your codebase, because of a decision made on the other side of a wall you decided wasn't yours.

So this article isn't about writing servers. It's about the part of the backend that's genuinely yours as a React developer: the contract. How you talk to the server — REST, tRPC, or a BFF — shapes your frontend more than most of us are willing to admit.

The Contract Is the Product

Here's the reframe that changed how I work: from the frontend, the backend is its API. You don't experience the database, the services, the queues. You experience the contract — the shape of the requests and responses. And a good contract makes the frontend small, while a bad one makes it a translation layer.

That's the lens for everything below. Not "which technology is trendy," but "which contract leaves the least incidental work in my React code." Because every gap between what the server sends and what the UI needs gets filled by you, in components that should be about rendering and instead are about reshaping data.

REST: The Default, and Its Real Cost

REST is the lingua franca. Everything speaks it, every tool supports it, and for a lot of applications it's completely fine. When someone hands me a well-designed REST API — sensible resources, predictable shapes, the fields I need where I expect them — I have no complaints. It pairs perfectly with TanStack Query, which was practically built for the REST request/response model.

The costs of REST are real but they're not "REST is bad." They're two specific frictions.

The first is over- and under-fetching. An endpoint returns a fixed shape. Sometimes that's more than your screen needs, so you ship kilobytes you throw away. More often it's less than you need, so you make a second call, then a third, and now one screen is a waterfall of requests you have to orchestrate and cache.

The second, and the one that actually costs me time, is types. A REST response is JSON — untyped by nature. On the client it arrives as any unless you do something about it. Which means the boundary between "typed React app" and "untyped network" runs right through your data layer, and you spend effort re-establishing types the backend already knew.

// The gap, made concrete:
const res = await fetch('/api/policies/42');
const policy = await res.json(); // any — the types stop here

// so you rebuild what the server already knew:
const policy = policySchema.parse(await res.json()); // Zod, by hand

That policySchema is you, manually, re-declaring a shape the backend already has in its own code. It works — I do it, and validating at the boundary with Zod is genuinely good practice. But notice what it is: the same truth, written twice, on two sides of the wall, kept in sync by discipline. Hold that thought, because the next option deletes it.

tRPC: When You Own Both Sides

If your backend is TypeScript, and especially if it's the same repo or monorepo as your frontend, tRPC changes the entire equation. It gives you end-to-end type safety with no schema, no code generation, no manual sync.

You define a procedure on the server, and the client just knows its types — inputs, outputs, everything — inferred straight across the boundary.

// server: the procedure
const policyRouter = router({
  byId: publicProcedure
    .input(z.object({ id: z.number() }))
    .query(({ input }) => getPolicy(input.id)), // returns Policy
});

// client: fully typed, no codegen, no fetch wiring
const policy = await trpc.policy.byId.query({ id: 42 });
//    ^? Policy — inferred end to end

Look at what disappeared. No policySchema written twice. No any at the network boundary. Rename a field on the server and your React code fails to compile before you run it — the contract enforces itself. This is the same instinct the whole series keeps returning to: one source of truth, let the compiler carry it. tRPC just extends that line across the network, which is the one place REST couldn't.

I'll be honest about the constraints, because they're firm. tRPC needs TypeScript on both ends, and it works best when the same team owns both. It's not for a public API consumed by clients you don't control, and it's not what you reach for when a separate backend team ships you REST or GraphQL. But for the shape this series keeps building — a TypeScript frontend and backend under one roof — it removes an entire category of busywork. When I control both sides, it's my default, for the same reason I pick every other tool in this series: it makes the frontend smaller.

GraphQL: The Over/Under-Fetching Answer

GraphQL deserves a fair mention, because it targets REST's first friction directly. The client asks for exactly the fields it needs — no more, no less — in one request, even across what would have been several REST resources. For a complex UI assembling data from many places, that's a real answer to the waterfall problem, and the typed schema helps on the client too.

I reach for it less than I used to, and it's a cost-benefit call, not a dismissal. GraphQL brings its own server, its own caching model, its own operational weight. On a large product with many clients and genuinely graph-shaped data, that weight pays for itself. On the mid-size TypeScript app this series targets, tRPC gets me most of the type-safety win for a fraction of the machinery. Right tool, right scale.

The BFF: A Backend That Works for the Frontend

There's one pattern worth knowing by name, because at some point you'll need it and it helps to know it has one: the Backend for Frontend.

The situation is familiar. You don't control the backend. It's a separate team, or several, exposing APIs designed for their convenience, not your screen's. Your dashboard needs data from three services in shapes that don't match what any of them return. The naive fix is to do all that stitching in React — three calls, merge, reshape, re-derive — and now your components are a data-integration layer wearing a UI costume.

A BFF is a thin server layer that belongs to the frontend and sits between your React app and those messy upstream services. Its whole job is to talk to them and hand your UI exactly the shape it wants, in one call.

// BFF endpoint: one call for the frontend,
// three upstream calls hidden behind it
async function getDashboard(userId: string) {
  const [profile, policies, claims] = await Promise.all([
    profileService.get(userId),
    policyService.listFor(userId),
    claimService.recentFor(userId),
  ]);
  return shapeForDashboard(profile, policies, claims); // exactly what the UI renders
}

The reason I like the BFF isn't just tidiness. It moves the stitching to where it belongs. Reshaping data, aggregating services, adapting an awkward upstream contract — that's backend work, and doing it in a Node BFF is cheaper, more testable, and more cacheable than doing it in React components. Your frontend goes back to rendering. And if you're already in a TanStack Start or Next.js world, you have a natural place to put a BFF without standing up a whole separate service.

The through-line to the whole article is right here: whenever you find your React code reshaping data, ask whether that reshaping belongs on the server instead. Usually it does.

How I Actually Decide

Strip it to the decision:

• A separate team ships you REST or GraphQL → consume it with TanStack Query, validate at the boundary with Zod, and consider a BFF the moment your components start stitching.
• You own a TypeScript backend, same repo or org → tRPC. End-to-end types, no manual sync, the frontend stays small.
• Complex graph-shaped data, many clients, real scale → GraphQL earns its weight.
• You don't own the upstream and the shapes fight your UI → a BFF, so the reshaping lives on the server where it's cheap.

None of this requires you to write a real backend. It requires you to have an opinion about the contract, and to push on it when it's making your frontend do work it shouldn't. That's the part that was always yours.

I used to think staying out of backend decisions kept my work clean. It did the opposite — it let other people's convenience become my complexity. The most leverage I've found as a frontend developer isn't a faster component or a cleverer hook. It's a better contract, argued for early, that makes half the frontend code simply unnecessary. You don't have to build the server. You do have to care what it sends you.

The next article goes one layer deeper into that same server: SSR and React with TanStack Start — where "frontend" and "backend" stop being two places and start being one framework, and what that does to everything we've built so far.

If you're staring at a React codebase that's mostly reshaping awkward API responses, that's usually a contract problem wearing a frontend costume — tell me what the API looks like and I'll tell you where I'd put the seam.

Authentication always starts as a login form. Two fields and a button. You could build that in an afternoon, and that afternoon is exactly the trap.

Because the form isn't the work. The work is everything the form implies. Where does the token live once the server hands it back? How does every subsequent request prove who you are? What happens when the token expires halfway through a multi-step action the user has been filling out for ten minutes? Who decides that this route is off-limits to this person, and where does that decision live so it can't be bypassed? None of that is visible in the login form, and all of it is auth.

So this article isn't about building a login screen. It's about the decision underneath it — buy versus build — and about the parts that stay your responsibility no matter which way you go. Because there's a security floor here that a nice-looking form quietly hides, and getting it wrong doesn't throw an error. It just leaves a door open.

The Honest Default: Don't Build It

I'll put my conclusion first, because I hold it strongly: for almost every application, you should not roll your own authentication.

This is not the usual "don't reinvent the wheel" reflex. Auth is a category where the cost of a subtle mistake is not a bug — it's a breach. Password hashing done slightly wrong. A token stored somewhere a script can read it. A session that doesn't actually invalidate on logout. A password-reset flow with a timing leak. These aren't exotic; they're the standard ways homegrown auth fails, and you usually find out about them from someone you'd rather not hear from.

Providers like Auth0, Clerk, and Supabase Auth — and the framework-native options like NextAuth/Auth.js — exist because a lot of very focused people have already made those mistakes so you don't have to. They handle the hashing, the token lifecycle, the reset flows, the MFA, the OAuth dance with Google and GitHub. Buying that isn't laziness. It's routing your effort to where your product is actually different, which is almost never "we hash passwords in a special way."

So my real advice is narrow: use a provider, and spend your energy integrating it correctly — because the integration is where the interesting decisions still live, and where you can still get it wrong.

Where Tokens Live Is the Whole Game

Here's the decision that matters most on the client, and the one people get wrong most often: once you're authenticated, where does the credential live in the browser?

The tempting answer is localStorage. It's easy, it persists across tabs and reloads, and the token is right there when you need it.

It's also readable by any JavaScript running on your page. That's the problem. If an attacker gets a script onto your site — a compromised dependency, a bad ad, an XSS hole — localStorage hands them the token directly. This is the single most common serious mistake I see in hand-rolled React auth, and it looks completely fine until the day it isn't.

The safer model is an httpOnly cookie: the server sets it, the browser sends it automatically, and JavaScript literally cannot read it. That removes the entire class of "a script stole the token" attacks. The trade-off you take on in return is CSRF — because the cookie is sent automatically, you now need CSRF protection — but that's a well-understood problem with standard defenses, and it's a better problem to own than token theft.

// The shape of the good answer, conceptually:
// - server sets an httpOnly, Secure, SameSite cookie on login
// - the browser attaches it to every request automatically
// - the React app never sees, stores, or touches the raw token
// - CSRF protection guards the state-changing requests

Notice what this does to your React code: the app stops managing tokens at all. It doesn't read them, store them, or attach them to requests. That's the goal. The less your frontend knows about the raw credential, the fewer ways it can leak one. A good provider integration leans exactly this way — and this is precisely the kind of thing you get for free by buying instead of building.

Auth State Is Just State — Treat It That Way

On the client, "am I logged in, and who am I?" is a piece of state like any other. The mistake is treating it as special and inventing a bespoke system for it, when the tools this series has already chosen handle it cleanly.

The current user is server state — it lives on the server, you fetch it, it can go stale. That makes it a TanStack Query concern, not a hand-built context with manual loading flags.

function useCurrentUser() {
  return useQuery({
    queryKey: ['currentUser'],
    queryFn: fetchCurrentUser,
    staleTime: 5 * 60 * 1000,
    retry: false,
  });
}

Now the whole app has one honest source of truth for identity. Logging out is a cache invalidation. A 401 from any request can trigger a refetch that flips the user to logged-out everywhere at once. You didn't build an auth state machine — you reused the data layer you already have, and it behaves consistently because it's the same machinery as the rest of your data. That consistency is the point I keep coming back to in this series: identity isn't a special island, it's server state, so it uses the server-state tool.

Guarding Routes: A Convenience, Not a Wall

This is the part where a dangerous misconception hides, so I want to be blunt about it.

Protecting a route on the client — redirecting away from /dashboard when there's no user — is a UX feature, not a security control. With TanStack Router you can gate a route in its beforeLoad, and you should, because showing a logged-out person a broken dashboard is bad UX.

export const Route = createFileRoute('/dashboard')({
  beforeLoad: ({ context }) => {
    if (!context.auth.user) {
      throw redirect({ to: '/login' });
    }
  },
});

But understand exactly what that does and does not do. It stops a browser from showing a page. It does nothing to stop a request from reaching your data. Anyone can open dev tools, read your bundle, and call your API directly — the client-side guard is irrelevant to them.

Client-side route guards decide what the UI shows. The server decides what the user can actually access. Only one of those is security.

The real protection lives on the server: every endpoint validates the session and authorizes the specific action, every time, as if the client did not exist. The React route guard makes the app pleasant for honest users. The server check makes it safe from everyone else. If you only build one, build the server one — an app with server checks and no client guard is merely awkward; an app with client guards and no server checks is wide open.

The Part No Provider Handles: The Expiry Moment

Buy the provider, store the token safely, guard your routes and your server — and there's still one moment that stays yours, because it's a UX problem, not a security one: the session dies while the user is in the middle of something.

Tokens expire. The user was filling out a long form (the exact painful form from the forms article), stepped away for coffee, came back, hit save — and the request comes back 401. What now?

This is where thoughtful apps separate from careless ones, and no library decides it for you. The naive answer is to hard-redirect to login and throw away everything they typed, which is how you make a user hate your product. The considered answer is a layer that catches the 401, attempts a silent token refresh if the provider supports it, retries the original request, and only if that genuinely fails preserves their work and prompts a re-login without discarding the form.

// Conceptual interceptor, not a full implementation:
// 1. request returns 401
// 2. attempt a silent refresh (if the provider offers refresh tokens)
// 3. on success -> retry the original request, user notices nothing
// 4. on failure -> keep their unsaved work, prompt a gentle re-login

The provider hands you the refresh capability. What you do with it — how gracefully you handle the moment a session dies under a user's hands — is product design, and it's entirely yours. This is the through-line of the whole article: buying auth doesn't remove your judgment, it relocates it. You stop deciding how to hash a password and start deciding how it feels when a session expires. The second decision is the one your users actually experience.

Where the Line Really Is

So the buy-versus-build question has a cleaner answer than it looks:

• Hashing, token issuance, OAuth, MFA, password resets → buy. This is the security floor, and the cost of building it wrong is a breach, not a bug.
• Where the token lives in the browser → yours, and httpOnly cookies over localStorage is close to non-negotiable.
• Auth state in the app → not special; it's server state, so it's a TanStack Query concern.
• Route guarding → client-side for UX, server-side for security, and never confuse the two.
• The expiry-mid-action moment → yours, and it's the difference between an app people trust and one they resent.

I buy authentication, and I'd tell you to as well — not because integrating it is trivial, but because buying it moves the hard part to where it belongs. The interesting work was never the login form. It's the token storage, the guard boundary, the graceful death of a session. That's the part that shapes the architecture, and that's the part that's still yours after you've paid someone else for the rest.

The next article follows this thread straight down: what a React developer actually needs to know about the backend — REST versus tRPC versus a BFF — because how you talk to your server decides more about your frontend than most of us admit.

If you've had a session expire under a user in a way that cost them real work — or if you're running localStorage tokens right now and want to talk through moving off them — reach out. That migration is one of the higher-leverage things you can do for an app's security, and I'm happy to compare notes.

A few weeks ago I wrote about giving your AI agent a persistent memory — a simple system of markdown files the agent reads and writes across sessions. I was excited about it. It worked. I rolled it out on my personal project, recommended it to colleagues, and eventually submitted a pull request adding the memory system to our main company repository.

That PR triggered something I did not expect.

A manager reached out and suggested organizing a meeting — not to approve or reject the PR, but because several people at the company had already been experimenting with similar ideas independently. Before the meeting even happened, there was a chat where people started sharing their experiences. Engineers who had been quietly running local memory systems of their own, not as a global company-wide thing, just something they had hacked together for themselves. They shared what worked and, more importantly, what did not.

What I heard in that chat changed how I think about this entirely.

What Broke

The first version of the system had one rule: append. Learned something? Append it. Fixed a bug? Append it. Session ended? Append a summary. Append, append, append.

This works fine for the first few days. Then the files get long. Then they get contradictory. Then they become a liability.

One story from the chat stuck with me. A colleague had been working in a long session — the kind where you get deep into something and lose track of time. The agent was faithfully logging each action to a sessions file, just as instructed. Then midway through, he asked it to do something simple. Small task. Nothing complicated.

The agent picked up the session logs, scanned the history, and concluded that several things from earlier in the session had not been completed yet. So it started doing them. All of them. On top of the actual task. Everything tangled together. The agent was trying to be helpful by using the context it had been given — and it made a mess precisely because of that context.

He rolled everything back and started a fresh session. Simple task, no history, done in two minutes.

That story captures the failure mode better than any metric I could give you. The agent did exactly what you told it to do. It dutifully loaded the history, applied it to the task, and produced chaos. The problem was not the agent. The problem was that we had built a system that grew without any mechanism for forgetting.

Here is what we also observed across different setups:

Context explosion. lessons.md hit 200 lines in three weeks. The agent was loading all of it into context on every session. Most of it was stale or irrelevant to the current task. We were paying context budget for noise.

Drift and contradictions. Decisions change. The agent would append a new decision without removing the old one. Now both exist. Which is current? Depends on where in the file the agent looks.

Entropy wins. The longer a system runs without maintenance discipline, the worse it gets. Append-only systems drift toward entropy by design.

We realized the core mistake: we treated memory like a log, not like a knowledge base.

The Redesign Principles

The meeting itself was candid in a way that work meetings rarely are. People with months of hands-on experience with these systems, and everyone had the same conclusion: the idea is right, but the implementation costs too much to maintain. The systems degraded. They required manual cleanup. They occasionally made things worse. The good news was that everyone had independently arrived at similar fixes — which meant the fixes were probably right.

The rewrite started with constraints rather than architecture. We asked: what properties does memory need to have to not degrade?

Memory is not a log. Do not store what happened. Store what matters. A session where nothing changed — nothing gets written.

If memory grows continuously, it is a bug. Not a feature, not normal accumulation. A symptom of missing update rules.

Overwrite, do not append. When knowledge changes, replace the old entry. The file should represent current state, not a history of states.

Load index first, fetch content lazily. The agent should never blindly load all memory into context. It should load a small index, decide what is relevant, then fetch only that.

One source of truth per topic. No two entries should describe the same thing differently. If they do, one is wrong and should be removed.

The New File Structure

.ai-memory/
  index.md          — What exists and when to load it
  state.md          — Current project state (short, always overwritten)
  decisions.md      — Architecture and product decisions (overwritten, not appended)
  facts.md          — Stable technical facts (rarely changes)
  tasks.md          — Active tasks only (no completed tasks)

Five files. No sessions folder. No history.

Notice what is gone: the sessions directory. We removed it. It was generating the most noise for the least value. If you need an audit trail, use git — that is what git is for. Memory is not git.

index.md

This is the only file the agent loads unconditionally at the start of a session. Everything else is fetched on demand.

# Memory Index

## Always load
- state.md — current project state, active focus

## Load when relevant
- decisions.md — when making architecture or tech stack decisions
- facts.md — when working with the API, data schema, or deployment
- tasks.md — when planning work or checking what is in progress

## Topics → files
- auth flow → facts.md#authentication
- API endpoints → facts.md#api
- styling rules → decisions.md#styling
- current sprint → tasks.md

The index is a routing table. The agent reads it, decides what it needs, loads only that.

state.md

One file, always overwritten. Never appended.

# Current State

Updated: 2026-04-11

## Active focus
Redesigning the memory system after observing degradation in production.
Building the hardened v2. Targeting minimal file count and no append logic.

## Recent context
- Completed: initial audit of degraded memory files
- Completed: team discussion and principles alignment
- In progress: implementing new structure across active projects

## Known blockers
None currently.

This is a snapshot, not a timeline. Next session, the agent rewrites it. Old state disappears. That is by design.

decisions.md

Decisions are updated in place. When a decision changes, the entry is rewritten — not a new entry added below.

# Decisions

## Styling approach
**Decision:** Tailwind CSS utility classes only.
**Reasoning:** Utility-first is fast for a small team, eliminates CSS naming arguments.
**Updated:** 2026-03-10

## Blog post storage
**Decision:** TypeScript files with markdown in template literals.
**Reasoning:** Type-safe content, no CMS needed, works with SSG.
**Updated:** 2026-03-15

Note the Updated field on every entry. This is the anti-drift mechanism. When you see a date from six months ago, you know to verify it is still current. When you update a decision, you update the date. Stale dates are a signal to review.

facts.md

Stable technical facts that rarely change. API shapes, schema, deployment configuration, environment behavior. Written once, updated when things change.

# Facts

## Authentication
- JWT tokens, 15-minute expiry
- Refresh tokens stored in httpOnly cookies
- Endpoint: POST /api/auth/refresh

## Deployment
- Static export via GitHub Actions
- Deployed to GitHub Pages
- Custom domain: ma-x.im
- Build command: next build (output: export)

## Data schema
- Blog posts: TypeScript files in src/data/posts/
- Each post exports { post: BlogPost }
- Registered in src/data/posts/index.ts

tasks.md

Active tasks only. Completed tasks are deleted, not archived.

# Active Tasks

## In progress
- Implement hardened memory structure across ma-x.im project

## Blocked
(none)

## Next
- Write documentation for the new structure
- Review and prune decisions.md across older projects

---
No completed tasks in this file. Completed = deleted.

This is a working board, not a history. Once a task is done, it disappears.

Update Rules: When to Write and When to Stay Silent

This was the most important thing we formalized. The first system had vague rules: "record things when appropriate." Agents interpreted this as "record everything always." The new rules are explicit about silence:

Write when:

• A decision was made that did not exist before
• An existing decision was changed
• A new stable fact was discovered
• The current focus shifted significantly
• A bug was encountered that reveals a non-obvious constraint

Do NOT write when:

• You completed a routine task (the task file handles this, no memoir needed)
• You repeated something already in memory
• The session produced no new knowledge
• You would only be adding a timestamp without changing content

Overwrite rules:

• state.md — always overwrite entirely
• tasks.md — remove completed tasks, add new ones
• decisions.md — edit the existing entry, update the date
• facts.md — edit in place, same as decisions

If you cannot identify which existing entry to update — stop and check if the new information belongs in memory at all.

Consolidation: What We Called "Dreaming"

One thing we kept from the meeting discussion was the idea of an explicit consolidation step. Call it memory maintenance, pruning, or — more evocatively — dreaming. The agent is not doing real work during this step. It is reviewing its own memory for quality.

The consolidation prompt looks like this:

Review all memory files. For each file:
1. Remove entries that are no longer current or relevant
2. Merge entries that describe the same thing
3. Resolve contradictions — keep the most recent or most accurate entry
4. Compress verbose entries into concise ones
5. Check that facts.md and decisions.md have Updated dates
6. Verify tasks.md contains only active tasks

Do not add new information during consolidation.
Output a summary of what was changed and why.

Run this manually every two to four weeks, or when memory files feel like they are growing again. It takes a few minutes and resets the quality level. Think of it as code review, but for your agent's knowledge.

Loading Strategy: Index First, Lazy Fetch

The old system: agent reads everything, every session. Expensive and noisy.

The new system: agent reads index.md first, then decides what to load.

Pseudo-logic the agent follows:

session_start:
  load index.md
  load state.md  (always — it is small and always relevant)

  if task involves technology decisions:
    load decisions.md
  
  if task involves API, schema, or deployment:
    load facts.md
  
  if task involves planning or sprint work:
    load tasks.md

session_end:
  if state has changed → overwrite state.md
  if a decision was made or changed → update decisions.md
  if new stable fact was discovered → update facts.md
  if tasks changed → update tasks.md
  if nothing materially changed → write nothing

The index also contains a topic-to-file routing table. If the task is about authentication, the agent looks up "auth" in the index, sees it maps to facts.md#authentication, and loads only that section if the file supports section loading.

Good Memory vs Bad Memory

Here is what the degraded system looked like, and what the hardened version looks like for the same information.

Bad — lessons.md after three weeks:

- Fixed a bug with template literals and backticks - need to escape them
- Tailwind is our CSS approach
- Remember to update the blog index when adding posts
- Spent 2 hours debugging the sitemap — turned out to be a missing trailing slash
- The agent keeps using CSS modules even though we use Tailwind — told it again
- Fixed template literal backtick issue again in a different file
- Reminder: blog posts need to be registered in index.ts
- Auth tokens expire after 15 min — need refresh logic
- AGAIN: escape backticks in template literals

Three separate entries about the same backtick bug. Two reminders about the blog index. This is what append-only looks like in practice.

Good — facts.md with a single consolidated entry:

## Blog post authoring
- Posts are TypeScript files in src/data/posts/, registered in index.ts
- Content is a template literal — backticks inside content must be escaped as \`
- Dates use format: "Apr 11, 2026"

One entry. Everything relevant. Zero repetition.

Honest Trade-offs

This system is better, but it is not free:

You lose history. There is no record of what was decided and then changed. If you care about that trail, decisions.md has Updated dates, but it does not track the previous value. For audit purposes, commit your memory files to version control — git gives you the history.

Consolidation requires effort. The dreaming step will not happen automatically unless you explicitly schedule it. Without it, even this system will degrade eventually — just much more slowly.

The agent still needs good instructions. Vague instructions produce vague memory behavior. The more specific your rules (especially the "do NOT write" cases), the more disciplined the output.

Index routing is manual. The topic-to-file mappings in index.md need to be maintained by hand. A stale index routes the agent to the wrong file. Keep it accurate.

Summary

I submitted that PR thinking I was sharing something solid. The pre-meeting chat humbled me a little — people had hit the same walls I had not hit yet, they just had not written about it publicly.

The honest conclusion from all of that experience: the naive version works until it does not, and when it stops working it does so quietly. You do not get an error. You get an agent that does almost the right thing, confidently, based on stale context you forgot was there. That is harder to debug than a crash.

The hardened version applies one core idea: memory should represent current knowledge, not accumulated history. Everything else follows from that — overwrite instead of append, index-based loading instead of bulk dumps, explicit silence rules, no sessions folder.

The agent does not need a journal. It needs a working knowledge base that stays reliable over time.

Build that instead.

The chart looked perfect in the demo. Clean line, smooth animation, a tooltip that felt expensive. Then real data showed up — forty thousand points instead of the twenty I'd tested with — and the tab froze solid every time you hovered.

That's the moment you learn charts aren't a UI problem. They're a rendering problem wearing a UI costume.

"Just use a chart library" is the advice everyone gives, and it's not wrong, exactly. It's just hiding the actual decision. There are a dozen chart libraries and they are not interchangeable. Picking one commits you to a rendering model, a customization ceiling, and a performance profile — and you usually discover all three at the worst possible time, which is after the design changes or the data grows.

So this article is about how I actually choose, and the question underneath the choice is the same one that decided the UI library article and the forms article: who owns the thing being rendered — the library, or me?

The Two Questions That Decide Everything

Before any library names, two questions do most of the sorting.

How much do you need to control the visuals? A dashboard with standard bar and line charts is a different problem from a bespoke visualization no chart library has a preset for. The first wants defaults. The second wants primitives.

How big is your data, and how interactive is it? A hundred points rendered as SVG is nothing. A hundred thousand points, hovering and zooming, is where SVG dies and you need Canvas or WebGL. This one question quietly eliminates half the options before you've read their docs.

Everything below is really just these two axes: control vs done-for-you, and data size vs interactivity. Hold them in your head and the landscape stops looking like a dozen equivalent choices.

Recharts: The Sensible Default

For the majority of what people actually build — dashboards, admin panels, the CRM-shaped screens this series keeps returning to — Recharts is where I start. It's React-native and composable: charts are components, and you build them the way you build the rest of your UI.

import { LineChart, Line, XAxis, YAxis, Tooltip } from 'recharts';

function RevenueChart({ data }: { data: MonthlyRevenue[] }) {
  return (
    <LineChart width={640} height={320} data={data}>
      <XAxis dataKey="month" />
      <YAxis />
      <Tooltip />
      <Line type="monotone" dataKey="revenue" stroke="#22c55e" />
    </LineChart>
  );
}

Look at what that is: no imperative setup, no lifecycle wiring, no D3 selections. Axes are components. The line is a component. You compose a chart the way you compose a form or a page, and it fits a React codebase without friction. For standard chart types it's readable, quick, and easy to hand to another developer.

The ceiling is real, though, and worth naming. Recharts is great until your design asks for something outside its component vocabulary — a custom axis behavior, an unusual interaction, a shape it doesn't ship. Then you're either fighting its internals or reaching for something lower-level. For 80% of dashboards that ceiling is far above what you need. For the other 20%, you feel it early.

There are close siblings here — Nivo, Victory, react-chartjs-2 — and I won't pretend to rank them precisely. Nivo's defaults are beautiful and it has a Canvas escape hatch for larger datasets. Chart.js (via react-chartjs-2) renders to Canvas out of the box, which helps with volume but makes it feel less React-native. They cluster in the same place: high-level, done-for-you, great until the design goes off-script.

visx: Primitives, Not Charts

When the design does go off-script — when you're building a visualization rather than picking a chart — visx is what I reach for.

visx (from Airbnb) is a set of low-level primitives built on D3's math, wrapped so React owns the rendering. D3 does the scales, the shapes, the layout calculations; React draws the actual SVG. You don't get a <BarChart>. You get scales, axes, shapes, gradients — the pieces — and you assemble the exact chart you want.

import { scaleLinear } from '@visx/scale';
import { Bar } from '@visx/shape';

const xScale = scaleLinear({ domain: [0, maxValue], range: [0, width] });

function CustomBars({ data }: { data: Point[] }) {
  return data.map((d) => (
    <Bar key={d.id} x={0} y={yScale(d.label)} width={xScale(d.value)} height={18} />
  ));
}

This is the same move as Radix and shadcn/ui from the earlier articles: the library gives you behavior and math, and hands the pixels back to you. The cost is honest — you write more, you think about scales and margins yourself, and there's no "just drop in a chart." The payoff is that there's no ceiling. If you can describe it, you can draw it, and React stays in control of every element.

I don't reach for visx for a revenue line chart. That would be building a table saw to cut one board. I reach for it when the visualization is the product feature, not a readout beside it.

Raw D3: Powerful, and at Odds with React

D3 is the foundation under most of this, and you can absolutely use it directly. I mostly don't, and the reason is architectural, not a knock on D3.

D3 wants to own the DOM. Its whole model is selecting elements and mutating them imperatively — enter, update, exit. React also wants to own the DOM, through its virtual model. Point them at the same nodes and you get two systems fighting over who's in charge, which shows up as subtle bugs where React re-renders away what D3 just drew, or vice versa.

The clean pattern is to split the roles: let D3 do the math, let React do the rendering. Use D3 for scales, layouts, and path generators — pure functions that take data and return numbers or SVG path strings — and let React turn those into elements. That's exactly what visx formalizes, which is why I'd rather use visx than wire that boundary by hand. If you do reach for raw D3 inside React, keep it to the calculation layer and let React render. The moment D3 starts calling .append() on nodes React manages, you've bought yourself a class of bugs that's genuinely hard to reason about.

The Thing Nobody Warns You About: SVG vs Canvas

Here's the constraint that ambushed me in the opening story, and it's independent of which library you pick.

Most chart libraries render to SVG, and SVG is wonderful — every point is a DOM node you can style, inspect, and attach handlers to. Until there are too many of them. Ten thousand DOM nodes is a slow page. Fifty thousand is a frozen one. The browser simply wasn't built to keep that many elements interactive.

Past that threshold you need Canvas (one element, drawn imperatively, no per-point DOM) or WebGL for the truly massive. This changes what you're allowed to pick. If you know up front you're plotting a hundred thousand time-series points with hover and zoom, that fact chooses your library before any aesthetic preference does — you filter to the ones with a Canvas renderer and decide from there. Choosing a beautiful SVG library and then discovering the data size is how you end up rewriting the chart layer under deadline.

So I've learned to ask the data-size question first, not last. It's the least glamorous input and the most decisive one.

How I Actually Decide

Strip it down and it's short:

• Standard dashboard charts, reasonable data size → Recharts. React-native, composable, done. This is most cases.
• Beautiful defaults, occasionally large data → Nivo, for its presets and Canvas option.
• A custom visualization that's a real product feature → visx. Own the pixels, no ceiling.
• Genuinely huge datasets, heavy interaction → a Canvas/WebGL renderer, and let data size lead the choice.
• Raw D3 → for the math, behind a React rendering layer. Rarely for the DOM directly.

For the Playbook, Recharts is the default and visx is the escape hatch — the same shape as every other choice in this series. Start with the composable, React-native option that agrees with the rest of the stack; drop to primitives only when the design demands it.

But I want to end where the real difficulty lives, because it isn't the library. The hard part of a chart is never the rendering — it's the data. Getting your series into the exact shape the chart wants, aggregating and bucketing correctly, choosing the visualization that answers the actual question instead of the one that looks impressive. A library renders whatever you hand it. It has no opinion on whether the chart is honest, or clear, or answering the right question. That part is yours, and no dependency will do it for you.

Data going in, data coming out — we've covered both. The next article turns to something every real app needs and everyone underestimates: authentication. Rolling your own versus buying it, and where that decision quietly reshapes your whole architecture.

If you've hit the SVG performance wall, or fought D3 and React over the same DOM, I'd like to hear how it went — those are the war stories where the interesting trade-offs actually surface, and I'm always collecting the ones I haven't run into yet.

Every codebase has one file everyone is a little afraid of. In the apps I've worked on, it's usually a form.

Not a login form. Those are fine. I mean the real one — the checkout, the policy application, the onboarding flow with the field that only appears when you pick "business account," which itself unlocks a tax ID field, which has to be validated against a server, but only after the user stops typing, and only if the country is one of four. That form. The one where every new requirement lands as another if somewhere in a 600-line component.

Forms are where clean React quietly falls apart. Everywhere else you can lean on good structure and it holds. Forms fight back. They mix local state, async work, cross-field logic, and user timing into one knot, and the naive version — a pile of useState and a submit handler that reads all of them — works right up until the requirements get real.

So this article is about the tool I reach for when a form stops being trivial, and, just as importantly, about the moment you actually need one. Because reaching for a form library too early is its own mistake.

When You Don't Need a Form Library

Let me start against my own topic. A lot of forms don't need a library at all.

function NewsletterSignup() {
  const [email, setEmail] = useState('');

  return (
    <form onSubmit={handleSubmit}>
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <button type="submit">Subscribe</button>
    </form>
  );
}

That's a form. It's fine. One field, no cross-field rules, validation you can do in a single line. Adding a library here buys you nothing but an import. I've seen people install a form framework for a search box, and it always reads like insecurity — reaching for structure the problem doesn't have yet.

The line I use is simple: the moment fields start depending on each other, or validation has to talk to a server, or the same form has more than a handful of inputs, the hand-rolled version starts costing more than it saves. Below that line, useState is the right answer. Above it, you want a real tool. Most interesting forms sit above it.

What Actually Makes Forms Hard

Before the library, it's worth naming what we're fighting, because the pain isn't "typing out inputs." It's four things that stack:

• State that spreads. Every field is state, but so is touched, dirty, validating, error, submitting. Multiply by twenty fields.
• Cross-field logic. Field B is required only if field A has a value. Field C's options depend on field D. The rules form a little graph.
• Async validation. "Is this username taken?" means a server round-trip, debounced, cancelable, with a pending state the UI has to show.
• Re-render cost. The naive approach lifts everything to one state object, so one keystroke re-renders the entire form. On a big form you feel it.

A good form library is really a tool for managing that specific mess. That's the lens I judge them through — not "does it render inputs," but "does it make those four things smaller."

Why TanStack Form

There are three names worth taking seriously: Formik, React Hook Form, and TanStack Form. I'll be fair to all of them, because none is a bad tool.

Formik was the default for years. It's stable and widely known. But its model re-renders broadly by default, and its TypeScript story shows its age — types feel bolted on rather than designed in. On a large, dynamic form you end up working around it.

React Hook Form is genuinely good, and if you're happy with it I won't try to talk you out of it. It's fast, because it leans on uncontrolled inputs and refs, and it's the right answer for a lot of teams. My hesitation is narrow: that ref-based, uncontrolled model gets awkward exactly where my forms get hard — deeply dynamic fields, tightly controlled components, cross-field reactivity. It optimizes for the common case in a way that can fight the uncommon one.

TanStack Form is the one I default to in this series, and the reason is consistency more than superiority. It's type-safe to the core — your field names, values, and errors are all inferred, so renaming a field is a compiler problem, not a runtime surprise. It's granularly reactive: you subscribe to the exact slice of form state a component cares about, and only that component re-renders. And it's headless and framework-agnostic, which means it makes no styling decisions and hands control back to you — the same principle that decided the UI library article.

If you've followed this series, that reactivity model should feel familiar. It's the same instinct behind the Reatom choice: fine-grained subscriptions instead of one big blob that re-renders on every change. A form is just reactive state with a lot of edges, and TanStack Form treats it that way.

The Shape of It

Here's the same policy form, the kind this series keeps circling, wired with TanStack Form.

import { useForm } from '@tanstack/react-form';

function PolicyApplication() {
  const form = useForm({
    defaultValues: {
      accountType: 'personal',
      holderName: '',
      taxId: '',
    },
    onSubmit: async ({ value }) => {
      await submitApplication(value);
    },
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        form.handleSubmit();
      }}
    >
      <form.Field name="holderName">
        {(field) => (
          <input
            value={field.state.value}
            onBlur={field.handleBlur}
            onChange={(e) => field.handleChange(e.target.value)}
          />
        )}
      </form.Field>
    </form>
  );
}

The verbosity is real, and I won't pretend otherwise — the render-prop Field component is more ceremony than React Hook Form's register. But look at what you get for it: field.state.value is typed from defaultValues, name="holderName" is checked against the same shape, and everything inside that Field re-renders in isolation. The ceremony is buying type safety and surgical re-renders. On a small form that's a bad trade. On the 600-line one, it's the whole point.

Conditional Fields Without the Spaghetti

This is the part that sold me. Remember the "business account unlocks a tax ID field" requirement — the one that becomes an if in a naive form. Here it's just reading one field's value to decide whether to render another.

<form.Subscribe selector={(state) => state.values.accountType}>
  {(accountType) =>
    accountType === 'business' ? (
      <form.Field
        name="taxId"
        validators={{
          onChange: ({ value }) =>
            value.length === 0 ? 'Tax ID is required for business accounts' : undefined,
        }}
      >
        {(field) => (
          <input
            value={field.state.value}
            onChange={(e) => field.handleChange(e.target.value)}
          />
        )}
      </form.Field>
    ) : null
  }
</form.Subscribe>

Two things matter here. First, form.Subscribe with a selector means only this branch re-renders when accountType changes — the rest of the form doesn't flinch. Second, the validation rule lives on the field that owns it, not in a giant central schema that has to know about every conditional. The tax-ID rule exists only when the tax-ID field exists. When the field unmounts, its rule goes with it. That co-location is what keeps dynamic forms from rotting.

Async Validation That Doesn't Fight You

The "is this taken?" problem is where hand-rolled forms accumulate the most incidental complexity — debouncing, cancellation, a pending flag, a race condition you didn't see coming. TanStack Form has a slot for exactly this.

<form.Field
  name="username"
  validators={{
    onChangeAsyncDebounceMs: 400,
    onChangeAsync: async ({ value }) => {
      const taken = await checkUsernameTaken(value);
      return taken ? 'That username is already in use' : undefined;
    },
  }}
>
  {(field) => (
    <>
      <input
        value={field.state.value}
        onChange={(e) => field.handleChange(e.target.value)}
      />
      {field.state.meta.isValidating && <span>Checking…</span>}
      {field.state.meta.errors[0] && <span>{field.state.meta.errors[0]}</span>}
    </>
  )}
</form.Field>

The library owns the parts that are easy to get subtly wrong: the debounce, the in-flight tracking via isValidating, cancelling a stale check when the value changes again. You own the one thing that's actually your business logic — the checkUsernameTaken call. That's the right division of labor. I don't want to write another debounced-async-with-cancellation dance by hand; I've written it enough times to know I'll get the edge case wrong.

Let the Schema Do the Talking

Inline validators are fine for one-off rules, but real forms usually already have a schema — and TanStack Form is happy to defer to it. Point a field's validator at a Zod schema and the types and the rules come from one source.

import { z } from 'zod';

const holderName = z.string().min(2, 'Name is too short');

<form.Field name="holderName" validators={{ onChange: holderName }}>
  {(field) => (/* … */)}
</form.Field>

Now the validation rule and the TypeScript type live in the same place, and neither can drift from the other. This is the same instinct as everything else in the series: one source of truth, let the compiler enforce it. A form is often where a Zod schema you already have — for your API payload — gets a second job validating the UI. Reuse it. Don't write the shape twice.

Where a Form Library Still Can't Save You

I want to end honestly, because it's easy to oversell this. A form library manages state, validation, and re-renders. It does not manage product complexity, and most painful forms are painful because the product is.

Multi-step wizards with a back button that has to preserve state. Fields whose valid options depend on an API call that depends on another field. Save-as-draft that has to serialize a half-finished form. A submit that's really five API calls with partial-failure handling. TanStack Form gives you a clean foundation for all of it — but the wizard's flow, the dependency graph, the draft format, the failure strategy are yours to design. The library keeps the state honest. It doesn't tell you what the state should be.

That's the realistic version. The right tool removes the incidental pain — the re-renders, the type drift, the debounce dance — so that what's left is the essential pain, the actual product logic. That's the most any library can do, and it's a lot. A form that only hurts where the problem is genuinely hard is a form you can live with.

For the Playbook, TanStack Form is the choice, for the same reason shadcn/ui and Reatom were: it's headless, type-safe, and granularly reactive, so it points the same direction as everything else we've built. Coherence over any single feature.

Forms handle the data going in. The next article is about making sense of data coming out — visualization and charting in React, and why "just use a chart library" is a much bigger decision than it sounds.

If you've got a form in your codebase that everyone tiptoes around, I'd genuinely like to hear what makes it hard — the specific requirement that broke the clean version. That's usually where the interesting design problems live, and I'm always looking for the ones I haven't hit yet.

The demo always goes well. That's the trap.

You're evaluating a component library. You drop in their date picker, their data table, their modal. In twenty minutes you have something that looks polished, and the decision feels made. Ship it.

The problems don't show up in the demo. They show up eight months later, when a designer hands you a spec that doesn't match the library's defaults, and you discover that changing one border radius means fighting three layers of the library's own styling system. That's when you learn what you actually signed up for.

So I've stopped evaluating UI libraries by how good the demo looks. The question I ask now is different, and it's uncomfortable:

When my design diverges from the library's defaults — and it will — who wins, me or the library?

That question splits the entire landscape cleanly. And it connects straight back to the styling decision from the previous article: once you've committed to Tailwind and a token system, a component library that brings its own styling engine isn't a neat addition. It's a second opinion arguing with your first one.

Let me walk through the four I actually consider — MUI, Ant Design, Radix, and shadcn/ui — grouped not by popularity, but by who holds the pen.

Two Families, Not Four Libraries

Before the individual names, the split that matters:

• Batteries-included, styled libraries — MUI, Ant Design. They give you finished, good-looking components and the styling system that drives them. You adopt their look and their theming model.
• Headless / you-own-the-styles — Radix, shadcn/ui. They give you behavior and accessibility, and hand the styling back to you.

Almost everything else follows from which family you pick. The first family gets you to "looks done" fastest. The second gets you to "looks like ours" without a fight. Neither is wrong. They're answers to different questions.

MUI: Powerful, Complete, and Opinionated

MUI (Material UI) is the library I'd hand someone who needs a lot of surface area, fast, and doesn't have a strong custom design language to protect.

import { Button, TextField } from '@mui/material';

function PolicyForm() {
  return (
    <form>
      <TextField label="Holder name" variant="outlined" />
      <Button variant="contained">Save</Button>
    </form>
  );
}

What's genuinely great: the component coverage is enormous. Data grids, date pickers, autocomplete, everything. The accessibility is solid. For an internal tool or a dashboard where "clean and consistent" beats "uniquely ours," MUI gets you there remarkably fast.

Here's my reservation, and it's the same one that decides most of this article. MUI brings its own styling engine — historically Emotion, a runtime CSS-in-JS system. You saw in the last article why I've cooled on runtime CSS-in-JS: the cost moved, and it sits awkwardly with Server Components. MUI inherits that tension. And it carries a point of view — Material Design — that you either want, or spend a long time theming your way out of. Overriding MUI deeply means learning MUI's override system, which is its own body of knowledge.

MUI isn't a bad choice. It's a committing choice. You're adopting a design language and a styling runtime along with the components.

Ant Design: Enterprise Density Out of the Box

Ant Design is MUI's closest sibling in philosophy, aimed at a slightly different target: dense, data-heavy enterprise applications.

If you're building an admin panel with complex tables, filters, and forms — the CRM-shaped software this series keeps circling back to — Ant's defaults are tuned for exactly that. The tables alone save weeks.

The trade-off is the same shape as MUI's, just with a different accent. You're adopting Ant's visual language, which is strong and distinctly Ant — apps built with it tend to look like they're built with it. Deep customization means working within Ant's theming system, and stepping outside its defaults gets progressively harder the further you go. Honestly, if your product needs to look like your brand rather than like an Ant demo, this is the friction you'll feel most.

Both MUI and Ant answer the question "how do I get a lot of good components quickly?" Well. The next two answer a different question: "how do I keep control of how everything looks?"

Radix: Behavior Without the Costume

Radix Primitives took the part that's genuinely hard — accessible, correct interactive behavior — and shipped only that. No visual design at all.

import * as Dialog from '@radix-ui/react-dialog';

function ConfirmDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Delete policy</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/40" />
        <Dialog.Content className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
          <Dialog.Title className="text-sm font-semibold">Are you sure?</Dialog.Title>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Look at what Radix gives you and what it doesn't. It gives you the dialog's focus trapping, escape-to-close, scroll locking, ARIA wiring, portal handling — all the things that are tedious and easy to get subtly wrong. It gives you no appearance. Every className there is mine, and it's Tailwind, and Radix doesn't care.

That's the whole point. Radix is what you reach for when accessibility matters and you refuse to inherit someone else's look. The cost is honest: you build the visual layer yourself. For a one-off that's work. Which is exactly the gap the last option fills.

shadcn/ui: The One That Fits This Series

shadcn/ui isn't really a library, and that's the clever part. It's a collection of components built on Radix, styled with Tailwind, that you copy into your own codebase.

You don't npm install a black box. You run a command, and the component's source lands in your project as your code:

npx shadcn@latest add dialog

Now components/ui/dialog.tsx is yours. Radix underneath for behavior, Tailwind classes for the look, and every line editable because it lives in your repo. There's no override system to learn — if you want a different border radius, you change the border radius, because it's just a file you own.

I'll be direct about why this fits the Playbook so well. We chose Tailwind and a token system in the last article. shadcn/ui is built on exactly that foundation — its components read from your Tailwind tokens, so they inherit your design system instead of imposing one. Radix gives the behavior I'd otherwise have to build by hand. And because the code is mine, the library can never become the thing I'm fighting. There's no black box to fight with.

The trade-off is real and worth stating: you own more code. Updates aren't an npm update — you re-pull components or merge changes by hand. For some teams that ownership is a burden. For a team that wants its product to look like itself and never wants to be trapped by a vendor's styling decisions, it's the feature, not the cost.

The Decision, Honestly

Strip away the popularity contests and it comes down to that one question — who owns the styling:

• You need enormous component coverage fast, and a strong custom look isn't the priority → MUI. Adopt its language on purpose.
• You're building dense, data-heavy enterprise screens → Ant Design. Its defaults are tuned for exactly that.
• You need accessible behavior but insist on owning every pixel → Radix primitives, styled yourself.
• You want owned, Tailwind-native components with Radix behavior underneath → shadcn/ui. This is my default for the kind of app this series builds.

Notice that the "right" answer flips entirely based on one thing: how much your product needs to look like yours versus how fast it needs to look done. There's no library that wins both, and anyone selling you one hasn't hit month eight yet.

For the Playbook, I'll build on shadcn/ui, because it's the choice that agrees with every decision we've made so far instead of arguing with one of them. That coherence — styling, tokens, components all pointing the same way — matters more than any single component's polish.

Components give you the pieces. The next article is about the hardest piece to get right: forms. We'll build real ones with TanStack Form, the kind with conditional fields, async validation, and the messy requirements that make forms the place UIs go to die.

If you're weighing a component library right now, do one thing before you commit: try to restyle its busiest component to look nothing like the default. However that fight goes is your real answer. And if you've made peace with MUI or Ant at scale and found the customization ceiling higher than I'm describing, tell me — I'd genuinely like to know where the line actually sits.

Ask ten React developers how to style a component and you'll start a fight.

Not a discussion. A fight. Tailwind people and CSS-in-JS people don't disagree about syntax — they disagree about identity. Somewhere along the way, "how do we apply styles" turned into a values debate, and the actual engineering question got buried under it.

Here's the thing that bugs me about that debate: almost none of it is about the question that matters. It's about which approach looks cleanest in a ten-line demo. But nobody styles a ten-line demo for a living. You style an application that grows, gets handed to new people, adds a design system halfway through, and has to survive a framework upgrade.

So the question I actually ask isn't "which one is prettiest." It's:

When this codebase triples in size and I wasn't the one who wrote half of it, which styling approach still makes sense?

That reframes everything. Let me walk through the real options the way I weigh them — Tailwind, CSS Modules, CSS-in-JS, and the zero-runtime newcomers — and where each one genuinely fits.

First, The Question Under The Question

Every styling approach is really answering three separate questions, and people conflate them:

1. Where does the style live? Same file as the component, a co-located file, or a global sheet.
2. When is the style computed? At build time, or at runtime in the browser.
3. How do you stay consistent? Ad-hoc values, or tokens and constraints.

Most "Tailwind vs styled-components" arguments are really arguments about question 2 without anyone saying so. Runtime cost is the thing that quietly decides a lot of this in 2026, especially with React Server Components in the picture. Keep those three questions in mind — they'll do more for you than any hot take.

Tailwind: The Default I Keep Coming Back To

I'll be honest about my bias up front: Tailwind is my default. Not because it's fashionable, and not without reservations. Because of what it does to a team, not to a single component.

function PolicyCard({ policy }: { policy: Policy }) {
  return (
    <article className="rounded-lg border border-slate-200 p-4 hover:border-slate-300">
      <h3 className="text-sm font-semibold text-slate-900">{policy.name}</h3>
      <p className="mt-1 text-xs text-slate-500">{policy.status}</p>
    </article>
  );
}

The first reaction most people have is "that's ugly, the markup is noisy." Fair. I had the same reaction. Then I worked in codebases where Tailwind had been the standard for a year, and the noise stopped mattering. Here's what I noticed instead:

• Nobody invents new spacing values. p-4 is p-4 everywhere. The design constraints are baked into the class names, so drift is hard.
• Deleting a component deletes its styles. No orphaned CSS rotting in a global file because everyone's afraid to remove it.
• No naming tax. I don't spend energy inventing .policy-card__status--pending. The cognitive cost of good CSS class names is real, and Tailwind just removes it.
• It compiles away. The output is a static stylesheet. Zero runtime style computation, which means it plays nicely with Server Components.

The trade-offs are real too, and I won't pretend otherwise. The markup is genuinely harder to scan at first. Long class strings need something like clsx or tailwind-merge once conditions appear. And onboarding someone who's never used it costs a day or two of "why is everything a class name."

The reservation I take most seriously: Tailwind is weak when a style is genuinely dynamic — driven by a value only known at runtime, like a chart bar's height from data. You don't want h-[347px] generated on the fly. For that, an inline style or a CSS variable is the right tool, and mixing them in is fine. Tailwind for the static 95%, a CSS variable for the dynamic 5%.

That's my honest position: Tailwind wins on team-scale maintainability, and that's the axis I care about most. But "it wins for me" is not "it wins for everyone," so let me give the alternatives a real hearing.

CSS Modules: The Boring, Correct Answer

If Tailwind's class soup is a dealbreaker for you, CSS Modules is the option I respect the most.

import styles from './PolicyCard.module.css';

function PolicyCard({ policy }: { policy: Policy }) {
  return (
    <article className={styles.card}>
      <h3 className={styles.title}>{policy.name}</h3>
      <p className={styles.status}>{policy.status}</p>
    </article>
  );
}

/* PolicyCard.module.css */
.card {
  border-radius: 0.5rem;
  border: 1px solid var(--color-border);
  padding: 1rem;
}

What I like: it's just CSS. No new mental model, no runtime, locally scoped class names so you can't leak styles across the app. It compiles to a static stylesheet, so like Tailwind it's Server Components-friendly. If a team has strong CSS skills and hates utility classes, this is not a compromise — it's a genuinely solid choice.

What pushes me away from it at scale: it doesn't enforce consistency on its own. Nothing stops one file from using padding: 16px and another using padding: 1rem and a third using padding: 14px because someone eyeballed it. You get scoping for free, but you have to build the discipline — the tokens, the shared variables — yourself. Tailwind ships that discipline in the box. That's the whole difference, and for some teams CSS Modules plus a well-guarded token file is exactly right.

CSS-in-JS: Why I'm Walking Away From It

This is the one where I've changed my mind, so I'll say it plainly.

I used to reach for styled-components and Emotion without a second thought. The developer experience is lovely: styles co-located with the component, full access to props, dynamic styling that feels natural.

const Card = styled.article<{ $pending: boolean }>`
  border-radius: 0.5rem;
  padding: 1rem;
  border: 1px solid ${(p) => (p.$pending ? '#f59e0b' : '#e2e8f0')};
`;

That reads great. So why am I walking away?

Because the cost moved. Runtime CSS-in-JS computes styles in the browser, on render, and serializes them into the DOM as the app runs. For years that cost was acceptable. Then React Server Components arrived, and runtime CSS-in-JS sits awkwardly with them — these libraries lean on runtime context and client-side execution, which is exactly what Server Components are trying to avoid. The React team's own guidance nudged people toward compile-time styling for a reason.

I don't say this to bury a whole category — if you're on a heavily client-rendered app and the DX makes your team faster, runtime CSS-in-JS is not a crime. But for new work in 2026, especially anything touching Server Components, I no longer start here. The direction of the ecosystem is away from runtime style computation, and I'd rather not build on the side that's swimming against it.

Which leads directly to the interesting middle ground.

Zero-Runtime CSS-in-JS: The Best of Both, Mostly

Tools like vanilla-extract keep the part of CSS-in-JS people actually love — writing styles in TypeScript, with type-safe tokens — while throwing away the part that hurts: the runtime.

// PolicyCard.css.ts
import { style } from '@vanilla-extract/css';
import { tokens } from '../theme.css';

export const card = style({
  borderRadius: tokens.radius.md,
  border: `1px solid ${tokens.color.border}`,
  padding: tokens.space.md,
});

You author in TypeScript, get autocomplete and type-checking on your design tokens, and it all compiles to a static stylesheet at build time. Zero runtime. Server Components-friendly. Honestly, this is the most intellectually satisfying option on the list — it fixes the exact thing that made me leave runtime CSS-in-JS.

So why isn't it my default? Two reasons, and neither is technical. The ecosystem and hiring pool around Tailwind are enormous, and the token-based type safety that vanilla-extract gives you, Tailwind approximates well enough through its config. If your team already thinks in TypeScript tokens and wants that safety enforced by the compiler, vanilla-extract is a genuinely excellent pick — arguably the "correct" one on paper. I just find Tailwind gets a team to the same maintainability with less setup.

The Thread That Ties It Together: Tokens

Notice what quietly showed up in almost every example above — var(--color-border), tokens.space.md, Tailwind's slate-200. That's the part that actually matters, and it's independent of which library you pick.

The styling library is a delivery mechanism. Design tokens are the actual system.

Whatever you choose, the thing that keeps a large app coherent is a single source of truth for color, spacing, radius, and typography — and the discipline to never bypass it with a magic number. Tailwind gives you tokens through its config. Vanilla-extract gives you tokens as typed objects. CSS Modules gives you tokens through CSS custom properties. The delivery differs; the principle doesn't. If you get tokens right, you can survive changing your styling library later. If you get them wrong, no library saves you.

So What Do I Actually Pick?

Stripped of tribalism, here's my honest decision path:

• New app, normal team, wants to move fast and stay consistent → Tailwind. It ships the constraints in the box.
• Team with strong CSS culture that dislikes utility classes → CSS Modules plus a guarded token file. Boring and correct.
• Team that lives in TypeScript and wants compiler-enforced tokens → vanilla-extract. The most "principled" pick.
• Heavily client-rendered app where runtime DX wins → runtime CSS-in-JS is still defensible, eyes open about Server Components.

There's no universally right answer, and anyone who tells you there is hasn't worked in enough different codebases. For this series I'll use Tailwind, because it fits the kind of app we're building and it pairs cleanly with what comes next.

Because styling rarely lives alone. The moment you have a real app, you reach for a component library — and how it's styled decides whether you can theme it, override it, or fight it. That's the next article: choosing a React UI library, and why the styling decision you just made quietly constrains that choice.

If your team is mid-argument about this right now, try changing the question. Stop asking which one is best and start asking which one your codebase can live with in two years. And if you've landed somewhere I'd disagree with — especially if you're still happily on runtime CSS-in-JS — I genuinely want to hear the case. I've changed my mind on this before.

The company had a legacy PHP application, and we were not brought in to rebuild it. We were brought in to add one module.

One module. A self-contained piece of the product that a couple of teams needed. Nobody expected it to matter much beyond that.

So when I pushed for structure — a real data model, immutable updates, clear boundaries — there was pushback. Fair pushback. "It's one module. Why the ceremony? Why can't we just mutate the thing and move on?"

I understood the argument. On a small, disposable module, discipline can look like pure overhead. You feel every extra rule slowing you down long before it pays you back.

Then the module did the thing small modules occasionally do. It got good. It got used. Other teams started building against it. Over a couple of years it quietly stopped being a module and became the main application, with almost everything bolted onto the shape we set at the start. I still talk to the people there. They are still building on that foundation today.

I'm not telling this to claim we were geniuses. We weren't. Most of what held up under that growth was boring. And one of the most boring rules of all was this: we never mutated state in place.

That's what this article is about. Immutable data in React — not the purity lecture, but the practical discipline. Where it bites you if you skip it, when the native approach stops being pleasant, and how it connects to the reactive model from the Reatom article earlier in this series.

If you know JavaScript, you already know how to copy an object. That's not the hard part. The hard part is understanding why React, memoization, and reactive stores punish you the moment you forget.

What Mutation Actually Breaks

React doesn't deeply compare your state. It compares references.

That single sentence is the whole thing. Everything else is a consequence of it.

Here's a bug I've watched people write, debug for twenty minutes, and never fully explain afterward:

const [draft, setDraft] = useState<PolicyDraft>(initialDraft);

function addBeneficiary(beneficiary: BeneficiaryDraft) {
  draft.beneficiaries.push(beneficiary); // mutation
  setDraft(draft);                        // same reference
}

You added a beneficiary. The data changed. The screen didn't.

React ran Object.is(previousDraft, nextDraft), saw the same object reference, and decided nothing changed. Your push mutated the array in place, so the outer draft object is still the exact same reference it was before. As far as React is concerned, you called setDraft with the value it already had.

The fix isn't a trick. It's a new reference:

function addBeneficiary(beneficiary: BeneficiaryDraft) {
  setDraft({
    ...draft,
    beneficiaries: [...draft.beneficiaries, beneficiary],
  });
}

New object, new array. React compares references, sees a difference, re-renders.

This is the React nuance the JS-fundamentals tutorials skip. Immutability in React isn't about being functionally pure for its own sake. It's that the entire rendering and memoization model is built on the assumption that a change produces a new reference. Break that assumption and everything downstream — React.memo, useMemo, dependency arrays, reactive stores — quietly stops working. Not with an error. With silence.

Mutation doesn't crash. It just makes your UI lie about the data.

The Rule: A New Reference On Every Change

The rule is boring, and boring is the point:

Never change data in place. Produce a new value.

For flat, shallow state, the native tools are enough, and I reach for them first.

Add an item:

const next = [...beneficiaries, newBeneficiary];

Remove by id:

const next = beneficiaries.filter((b) => b.id !== removedId);

Update one item by id — the operation people get wrong most often:

const next = beneficiaries.map((b) =>
  b.id === targetId ? { ...b, share: newShare } : b,
);

Notice what map does here. Every item that didn't change keeps its original reference. Only the one you touched becomes a new object. That's not an accident — it's exactly what you want. Components rendering the untouched rows can skip re-rendering, because their props are referentially identical.

Update a field on an object:

const next = { ...draft, holderName: 'Updated Name' };

None of this is clever. That's the appeal. Anyone reading it can see what changed and what stayed the same.

Where Native Updates Get Painful

Then the state gets nested, and the spreads start to hurt.

Say the policy draft looks like this:

interface PolicyDraft {
  holderName: string;
  sections: {
    coverage: {
      type: 'standard' | 'premium';
      limits: {
        medical: number;
        liability: number;
      };
    };
  };
}

Now update limits.medical immutably with native syntax:

const next = {
  ...draft,
  sections: {
    ...draft.sections,
    coverage: {
      ...draft.sections.coverage,
      limits: {
        ...draft.sections.coverage.limits,
        medical: newValue,
      },
    },
  },
};

Technically correct. Practically miserable. You changed one number and wrote a five-level spread pyramid to do it. Worse, in a code review nobody can see at a glance what actually changed — the signal is buried under structural boilerplate. And every one of those spread levels is a place to make a typo that silently drops a branch of state.

This is the moment people conclude "immutability is exhausting" and start looking for shortcuts. Some of those shortcuts are good. One of them is a mistake.

Immer: The Escape Hatch for Deep Updates

When updates get deep, I reach for Immer.

Immer lets you write code that looks like mutation and hands you an immutable result:

import { produce } from 'immer';

const next = produce(draft, (d) => {
  d.sections.coverage.limits.medical = newValue;
});

That's the same nested update as above. One line. You mutate a temporary draft object; Immer records the changes and produces a new immutable value, reusing every branch you didn't touch. That last part matters: the holderName string and the untouched liability limit keep their references, so referential-equality checks and memoization still work. You get the ergonomics of mutation with the guarantees of immutability.

My rule of thumb is narrow on purpose:

• Flat or shallow state → native spreads. Don't pull in Immer to change one field on a flat object. It's noise.
• Deep or awkwardly nested updates → Immer. The moment the spread pyramid appears, produce earns its place.

Immer isn't free. It wraps your drafts in proxies and freezes output in development, which is a real runtime cost. For application state — forms, drafts, workflow models — that cost is invisible. I would not reach for it inside a hot render loop or a tight animation frame. Right tool, right layer.

Why I Skip Immutable.js

Every time this topic comes up, someone asks about Immutable.js. It gives you Map, List, and structural sharing baked in, so surely it's the "serious" choice?

Honestly, no. Not in a modern React codebase, and not for me.

The problem isn't the data structures. They're well made. The problem is that Immutable.js introduces a parallel type system that doesn't speak plain JavaScript:

const draft = Map({ holderName: 'Ann', beneficiaries: List() });

const name = draft.get('holderName');        // not draft.holderName
const next = draft.set('holderName', 'Bob'); // not { ...draft }
const plain = draft.toJS();                  // needed at every boundary

That toJS() at the boundary is the tell. Your API returns plain objects. TanStack Query caches plain objects. TanStack Form, most component libraries, your logging, your TypeScript types — all assume plain objects. So you spend your life converting in and out, and every conversion is a place for bugs and lost type information. The TypeScript ergonomics are genuinely worse than working with plain interfaces.

Native immutable updates plus Immer for the deep cases cover everything Immutable.js was solving, without forcing the entire codebase to adopt a second notion of what "an object" is. I stopped considering it years ago and haven't missed it once.

Immutability and Reatom

This is where the previous article and this one meet.

In the Reatom piece, the whole model was a graph: small atoms, derived atoms, actions as transitions. That graph runs on the exact same assumption React does — a change is a new reference. Reatom decides what to recompute and what to re-render by comparing atom values by reference. Mutate an atom's value in place and you reproduce the React bug one layer down: derived atoms don't recompute, subscribed components don't update.

So the wrong version:

export const addBeneficiary = action((ctx, beneficiary: BeneficiaryDraft) => {
  const draft = ctx.get(policyDraftAtom);
  draft.beneficiaries.push(beneficiary); // mutation
  policyDraftAtom(ctx, draft);           // same reference — nothing reacts
}, 'addBeneficiary');

And the right one:

export const addBeneficiary = action((ctx, beneficiary: BeneficiaryDraft) => {
  const draft = ctx.get(policyDraftAtom);

  policyDraftAtom(ctx, {
    ...draft,
    beneficiaries: [...draft.beneficiaries, beneficiary],
  });
}, 'addBeneficiary');

And when the transition is deep, Immer lives comfortably inside an action:

import { produce } from 'immer';

export const setMedicalLimit = action((ctx, medical: number) => {
  const draft = ctx.get(policyDraftAtom);

  policyDraftAtom(ctx, produce(draft, (d) => {
    d.sections.coverage.limits.medical = medical;
  }));
}, 'setMedicalLimit');

Immutability isn't a nice-to-have bolted onto the state graph. It's the thing that makes the graph work at all. The reactivity you get from Reatom is paid for by never mutating in place.

The Payoff

Everything so far sounds like rules. Here's what the rules buy you, and it's the reason that small module survived becoming a large application.

Memoization actually works. Because unchanged branches keep their references, React.memo and derived atoms skip work honestly. You don't fight spurious re-renders, because your data stops lying about what changed.

Undo becomes boring. The undo history from the Reatom article only works because every previous draft is a distinct, frozen-in-time reference. If you mutated in place, "history" would just be a list of pointers to the same object, all mutating together. Immutability is what makes a snapshot an actual snapshot.

const history: PolicyDraft[] = [];

// every entry is a real, independent snapshot — because we never mutate
history.push(currentDraft);
policyDraftAtom(ctx, nextDraft);

Optimistic updates are safe. You apply the optimistic value as a new reference, keep the previous one, and roll back to it if the request fails. No cloning gymnastics, no fear that the rollback value mutated underneath you.

Debugging tells the truth. A logged state object stays what it was when you logged it. No more "it was correct in the console but wrong in the UI" — the classic symptom of an alias mutating after you inspected it.

None of these are exotic. They're the everyday properties that let a codebase absorb requirements it wasn't designed for. Which is exactly what that module had to do.

The Rule I Stopped Arguing About

The early pushback was really about ceremony. Immutability looked like ceremony — extra rules, extra keystrokes, extra discipline for a module nobody thought would grow.

But the module grew, and the ceremony turned out to be the cheapest insurance we bought. Not because immutability is profound. Because it removed an entire category of bug — the silent, intermittent, "works until it doesn't" kind — right at the point where scale makes those bugs most expensive to find.

I don't argue about immutability anymore. When someone asks whether it's worth the trouble on a small piece of code, I've stopped debating it. I just don't mutate. The habit costs almost nothing, and it holds up under exactly the pressure you can't predict when you're writing "just one module."

Next in the series, we move from data to what the user actually sees: styling in React, and why I keep coming back to Tailwind after trying most of the alternatives.

If you've got a state bug that only shows up sometimes — the kind that vanishes the moment you add a console.log — go looking for something mutating in place. And if you want to compare notes on where Immer genuinely earns its keep versus where it's overkill, reach out. I have opinions, and I'm happy to hear yours.

I was mass-scrolling LinkedIn and almost missed it. A post from Dmytro Sergiev — a Product Manager, not an engineer — about how he gives his AI agent a persistent memory using plain folders and markdown files. And something clicked.

I had been annoyed for months. Every new chat session with an AI agent — same questions, same wrong assumptions, same "what framework are you using?" dance. I would explain my project setup, my conventions, my stack. The agent would do decent work. Next day — blank slate. All of it, gone. I knew the problem was not the model itself — I understood that AI needs context to be useful. But I could not figure out a sustainable way to give it that context. The problem was amnesia.

Dmytro's idea was dead simple: give the agent a folder it can read and write between sessions. I grabbed this concept, adapted it for my frontend engineering workflow, and started rolling it out across every project I work on. It has been a few weeks now, and honestly — I cannot believe I worked without this for so long.

Update — April 2026: This post describes v1 of the system. After about three weeks of real use — across multiple projects and a team discussion — I ran into the limits of the append-only approach and redesigned it from scratch. The core idea here still holds and is worth reading for context. The hardened version is in The AI Agent Memory System I Built Was Broken — Here Is the Redesign.

The Problem Is Not the Model — It Is the Amnesia

Think about what happens when you open a fresh chat and say "add a blog post to my site." The agent has no idea what framework you use. It does not know how your content is structured. It does not know you spent two hours last Tuesday figuring out that your blog posts are TypeScript files with markdown in a template literal. It does not know that you tried CSS-in-JS once and it was a disaster.

So it guesses. You correct. It guesses again. You correct again. Twenty minutes pass before any real work happens. And tomorrow? Same thing. From zero.

I always understood that the model needs context. That was never the question. The question was — how do you actually give it enough? Context is not a document you write once. It is years of decisions, conventions, mistakes, preferences — all living in your head. You cannot dump all of that into a prompt. And even if you could, it would be out of date by next week. I needed a system, not a one-time fix.

The Fix: A Folder the Agent Can Read and Write

Create a .ai-memory/ folder in your project root. Put a few markdown files in it. Tell the agent to read them at the start of every session and update them as it learns. Seriously, that is the whole idea.

.ai-memory/
  context.md       — What this project is, who works on it, goals, constraints
  decisions.md     — Key decisions made, with reasoning
  patterns.md      — Conventions, naming rules, recurring patterns
  lessons.md       — Mistakes, gotchas, things to avoid
  sessions/
    2026-03-25.md  — What was done today, what was learned
    2026-03-24.md  — Yesterday's session

Five files and a folder. No database. No API. No npm packages. Just markdown files that a human can read too.

What Goes in Each File

context.md is the project's identity card. Who you are, what the project does, the tech stack, the constraints. For a React project it might say "Next.js 15, App Router, Tailwind, deployed to Vercel." For a marketing project it might say "Brand guidelines in /docs, tone is professional but warm, target audience is B2B SaaS." For an accounting workflow it could describe the tools, the report formats, the compliance rules.

decisions.md captures the "why" behind choices. Not just "we use Tailwind" but "we use Tailwind because utility-first is fast for a small team and avoids CSS naming debates." When the agent encounters a similar decision later, it does not propose something contradictory.

patterns.md records how things are done in this specific project. File naming conventions. Component structure. How blog posts are stored. Where images go. The things a new team member would ask on their first day — except the agent finds them on its own.

lessons.md is the file that surprised me the most. I did not expect it to matter this much. Every bug, every gotcha, every "do not do this because..." entry prevents the agent from repeating the same mistake. I had a bug in one of my projects where backticks inside a template literal were breaking the build. I fixed it, moved on, and the next day the agent generated the exact same bug. After I added "backticks inside template literal content must be escaped" to lessons.md — never happened again. Three words in a markdown file saved me from debugging the same issue three times.

sessions/ logs keep a running history. After each session the agent writes what it did, what decisions were made, what was learned. These logs feed future sessions with recent context.

Why This Works for Everyone — Not Just Engineers

Here is what struck me about Dmytro's original post: he is not a developer. He is a Product Manager who works with data, strategy, and AI-assisted research. He does not write React components. He uses VS Code as a workspace for documents and workflows. And the memory system works just as well for him — maybe better, because his context is even harder for an agent to guess.

Think about an analyst who works with multiple data sources, specific report formats, metric definitions that differ between clients, and compliance rules that change quarterly. Every time they start a new AI session, they would have to re-explain all of that. With a memory folder, the agent already knows: "Client X uses quarterly cohort analysis, reports go in /reports/YYYY-QN/, retention is measured as 30-day active, not 30-day login." That is not code. That is just domain knowledge written in plain text. And it makes the agent dramatically more useful.

The same applies to product managers tracking sprint context, designers recording spacing conventions and color tokens, writers maintaining tone guidelines. The files are plain markdown. No code required. If you can write a bullet point, you can give your agent a memory.

The Practical Difference

Let me give you a real example. Last week I came back to a project I had not touched in six days. Old me would have spent the first 15 minutes re-explaining the setup: "This is a Next.js site, blog posts are TypeScript files, we use Tailwind, content goes in src/data/posts..." Instead, I just said "create a new blog post about agent memory." The agent read context.md and patterns.md, understood the file structure, the naming conventions, the BlogPost type — and produced a working post file on the first try. Fifteen minutes of setup reduced to zero.

Or this one: I kept correcting the agent — "we use Tailwind, not CSS modules." Every. Single. Session. After I wrote it in decisions.md, that correction disappeared permanently. A one-line entry fixed a daily annoyance.

The thing that gets me is how it compounds. After a week, the agent knows your project better than a new team member after onboarding. After a month, going back to a project without memory feels broken — like opening a codebase with no README, no comments, nothing. You realize how much invisible context you were carrying in your head and re-typing every day.

How to Set This Up in Any Project

Here is the step-by-step. Takes about five minutes.

Step 1: Create the folder structure in your project root:

mkdir .ai-memory
mkdir .ai-memory/sessions

Step 2: Create the instruction file. If you use VS Code with GitHub Copilot, put this in .github/copilot-instructions.md. If you use Claude/Cursor, put it in .cursorrules or the equivalent config file.

Here is the full prompt you can copy:

# Agent Memory System

You have access to a persistent memory system stored in .ai-memory/
at the root of this project. Use it to maintain context across sessions,
avoid asking repeated questions, and make better decisions over time.

## Memory Structure

.ai-memory/
  context.md       — Project identity, tech stack, goals, constraints
  decisions.md     — Key technical decisions with reasoning
  patterns.md      — Conventions, naming patterns, project-specific rules
  lessons.md       — Mistakes, gotchas, things to remember and avoid
  sessions/
    YYYY-MM-DD.md  — Session log: what was done, decided, learned

## Rules

### At the Start of Every Session
1. Read context.md, decisions.md, patterns.md, and lessons.md.
2. Use this information to inform your work. Do not ask questions
   already answered in these files.
3. If a file does not exist yet, create it when you have information
   worth recording.

### During Work
- Non-trivial decisions -> record in decisions.md
- Discovered conventions -> record in patterns.md
- Bugs, gotchas, mistakes -> record in lessons.md
- Project goals or constraints -> update context.md

### Mandatory Memory Checkpoints
You MUST update memory at these moments. Do not skip. Do not defer.
1. After fixing a bug or discovering a gotcha -> add to lessons.md immediately.
2. After completing a multi-step task -> update relevant memory files right away.
3. When the user shares a preference or constraint -> update context.md or patterns.md within the same response.
4. Before responding with "done" -> check if anything should be in memory first.

### After Significant Work
- Create or append to sessions/YYYY-MM-DD.md with:
  what was done, key decisions, lessons learned.

### Writing Style
- Concise: 1-3 sentences per entry
- Factual: what was decided, not how you feel
- Append-friendly: new entries at the bottom
- No duplication: update existing entries, do not contradict

### If .ai-memory/ Does Not Exist
Create the folder and initial files by scanning the project:
package.json, README, configs -> context.md and patterns.md.
Leave decisions.md and lessons.md mostly empty — they grow over time.

Step 3: Start a new session. The agent will read the instruction, create the initial memory files by scanning your project, and begin maintaining them automatically.

Step 4: Decide where memory lives.

If this is your personal project — commit .ai-memory/ to the repo. You are the only one working here, so your memory is the project's memory. That is how I do it on ma-x.im.

If you work in a team — even three developers — add .ai-memory/ to .gitignore. Memory is personal. Your thinking, your mistakes, your patterns — they are different from your colleague's. General project knowledge (architecture, API conventions, component rules) belongs in shared context files like .github/copilot-instructions.md. But memory is your private notebook. The instruction prompt stays in the repo so every developer's agent knows to create and maintain its own local memory — but the memory content itself stays local.

There is a possible third path: shared team memory where everyone writes to the same folder. I can see how it could work in theory, but I have not seen a strong use case for it yet. Shared context plus individual memory covers most scenarios.

Honest Limitations

This is not magic. A few things to keep in mind:

• The agent forgets to update memory. This was my biggest surprise. I wrote clear instructions: "after fixing a bug, record it in lessons.md." The agent would fix the bug, confirm it was done, and move on without writing anything down. Hours of work, zero memory updates. The fix was adding explicit mandatory checkpoints to the instructions — not "record things when appropriate" but "you MUST update memory BEFORE telling me you are done." Passive instructions get ignored during complex multi-step work. Forceful, specific checkpoints work.
• Files can get bloated. If lessons.md grows past 100 lines, split it or prune old entries. The agent reads these files every session — keep them focused.
• It depends on the agent following instructions. Some AI tools respect system prompts better than others. GitHub Copilot in VS Code and Claude in Cursor both handle this well. Other tools may vary.
• It is not a replacement for proper documentation. This is a working notebook, not a wiki. Keep real docs in real docs.

Context vs Memory — Why You Need Both

This is the distinction I wish someone had explained to me earlier.

Context is what describes the project: architecture, API structure, component conventions, CSS rules, TypeScript config, deployment pipeline. It is documentation. You write it once, maintain it as the project evolves, and every developer on the team reads the same version. Context lives in shared files — README, copilot-instructions.md, architecture docs.

Memory is what describes the developer: your decisions, your mistakes, your patterns, your working style. It grows organically, session by session. What you did today, what went wrong yesterday, what you learned this week — this is what makes the agent smarter over time. Context is static knowledge. Memory is accumulated experience.

In an ideal project, you need both. Context so the agent understands the codebase. Memory so it understands you. Without context, the agent guesses about your stack. Without memory, it repeats the same mistakes and asks the same questions every day.

The real shift for me was understanding that context alone is never enough. There is always more knowledge in your head than you can write down — it forms over months and years of working on a project. You cannot capture all of it upfront. The memory approach solves this differently: instead of trying to dump everything at once, it lets knowledge accumulate naturally. Every session teaches the agent something new. After a week it knows your project better than a new hire after onboarding. After a month, working without it feels broken.

Summary

I always knew the model needed context. That was never the mystery. What I could not figure out was how to give it enough context without spending half my day writing documentation that would be outdated by Friday. The memory approach solved this — not by asking me to write everything upfront, but by letting knowledge accumulate naturally, session by session.

Five markdown files and a prompt. Five minutes of setup. The return is immediate and it compounds — every session makes the next one smarter.

The people chasing the newest model are solving the wrong problem. The leverage is not in the model. It is in what the model knows about you and your project.

If you have feedback, alternative approaches, or just want to discuss this topic — feel free to reach out.

The policy builder did not look dangerous at first.

It was "just a form." A few sections, some conditional fields, a Save Draft button, a final Submit action. We already had TanStack Query for server state and TanStack Form for field state. It felt like the rest could live in component state.

Then the requirements arrived one by one.

If the user changed coverage type, three sections had to recalculate. If they removed a beneficiary, dependent warnings had to disappear. If they switched tabs, the draft had to stay alive. If the API returned a validation warning, it had to attach to a section that might not be mounted. If they clicked Review, the app had to derive a summary from fields, rules, permissions, and unsaved changes.

Nothing was individually hard. Together, it became a graph.

I've been in this room before. Different company, different domain, same shape. A workflow starts as local state. Then you add a context. Then a reducer. Then a few selectors. Then effects hidden in components. Eventually nobody can answer a simple question: when this value changes, what else reacts?

That is the point where I want a state management library.

Not for every boolean. Not for every modal. For the moment client state becomes a reactive model instead of a component detail.

The question is not "do we need global state?" The question is "does this workflow have a state graph?"

This is article #7 in the React Playbook series. We already covered TanStack Query and TanStack Router. Now we need the missing piece: client state that does not belong to the server, but has outgrown useState.

Query Is Not Your Client Store

TanStack Query owns server state.

Policies from the API. Customer records. Coverage types. Search results. Anything fetched, cached, invalidated, and synchronized with a backend.

Client state is different:

• which policy sections are expanded
• current unsaved draft
• selected rows in a table
• multi-step wizard progress
• temporary validation warnings
• optimistic local operations before submit
• undo history
• derived review summary

The mistake is pushing these into Query because Query is already installed.

queryClient.setQueryData(['policy-builder-draft'], draft);

This works mechanically. It is also the wrong abstraction. Query cache is built around remote data identity, freshness, invalidation, refetching, and synchronization. A local draft is not stale. It should not refetch. It does not have server freshness semantics.

Use Query for server state.

Use a client-state tool for client state.

Why Not Just useState?

useState is still the default.

For component-local state, it is perfect:

const [isOpen, setIsOpen] = useState(false);
const [selectedTab, setSelectedTab] = useState<'details' | 'activity'>('details');

Do not install a state library for that.

useReducer is good when one component owns a local state machine:

const [state, dispatch] = useReducer(policyWizardReducer, initialWizardState);

Still fine.

The trouble starts when state has to be shared, derived, observed, and changed from multiple places.

In the policy builder:

• The wizard footer needs to know whether any section is dirty.
• The review page needs a derived summary.
• Section components need local edits.
• Autosave needs to react to draft changes.
• Permission logic needs to disable actions.
• Validation warnings need to attach to sections.

You can put all of this in context. But context broadcasts. Every consumer becomes part of the same render conversation. You can split contexts. Then you manage context architecture. You can write selectors. Then you are building a state library slowly, without the debugging tools or mental model.

That is where Reatom enters.

Why Reatom

I like Reatom for workflows where state is a graph.

Small atoms. Derived atoms. Actions. Effects. Explicit dependencies. React components subscribe to the pieces they read, not to a giant provider value.

The important thing is not the library name. The important thing is the model:

Break client state into small atoms, derive what can be derived, and make actions the place where transitions happen.

That model fits complex frontend workflows better than a single reducer object or a large Zustand store.

Zustand is excellent for simple global stores. I use it happily for small apps: auth-ish UI state, sidebar preferences, feature flags, lightweight cross-component state.

But for CRM-scale workflows with derived state, undo, chained reactions, and local process logic, I prefer a graph. Reatom makes the graph visible.

A Small Policy Builder Model

Imagine the policy builder feature:

src/
  features/
    build-policy/
      model/
        policy-builder.atoms.ts
        policy-builder.actions.ts
        policy-builder.selectors.ts
      ui/
        PolicyBuilderPage.tsx
        CoverageSection.tsx
        BeneficiariesSection.tsx
        ReviewPanel.tsx
      index.ts

The model belongs to the feature because the state exists for this workflow. It is not an entity. It is not shared. It is not a generic app store.

Start with atoms:

// src/features/build-policy/model/policy-builder.atoms.ts
import { atom } from '@reatom/core';

export interface PolicyDraft {
  holderName: string;
  coverageType: 'standard' | 'premium';
  beneficiaries: BeneficiaryDraft[];
}

export const policyDraftAtom = atom<PolicyDraft>(
  {
    holderName: '',
    coverageType: 'standard',
    beneficiaries: [],
  },
  'policyDraftAtom',
);

export const activeSectionAtom = atom<PolicySection>('coverage', 'activeSectionAtom');

export const dirtySectionsAtom = atom<Set<PolicySection>>(
  new Set(),
  'dirtySectionsAtom',
);

Small atoms. Named atoms. No giant policyBuilderStore object with everything inside.

Why?

Because different components care about different parts. The coverage section should not rerender because the beneficiaries list changed. The review panel might care about the full draft, but the active tab indicator only cares about activeSectionAtom.

Derived State Should Be Derived

Dirty state often gets stored badly.

const [canSubmit, setCanSubmit] = useState(false);

Then you remember to update it after every draft change, every validation change, every permission change. Or you forget, and the button lies.

Derived state should be computed from source state:

// src/features/build-policy/model/policy-builder.selectors.ts
import { atom } from '@reatom/core';
import { dirtySectionsAtom, policyDraftAtom } from './policy-builder.atoms';

export const hasUnsavedChangesAtom = atom((ctx) => {
  return ctx.spy(dirtySectionsAtom).size > 0;
}, 'hasUnsavedChangesAtom');

export const reviewSummaryAtom = atom((ctx) => {
  const draft = ctx.spy(policyDraftAtom);

  return {
    holder: draft.holderName || 'Missing holder name',
    coverage: draft.coverageType,
    beneficiaryCount: draft.beneficiaries.length,
  };
}, 'reviewSummaryAtom');

The exact Reatom API can vary by package setup, but the principle is stable: derived atoms observe source atoms and recompute when dependencies change.

No manual synchronization.

No effect that says "when A changes, update B."

B is a function of A.

Actions Are Transitions

I do not want random components mutating atoms however they like.

For meaningful workflow changes, define actions:

// src/features/build-policy/model/policy-builder.actions.ts
import { action } from '@reatom/core';
import { dirtySectionsAtom, policyDraftAtom } from './policy-builder.atoms';

export const updateCoverageType = action(
  (ctx, coverageType: PolicyDraft['coverageType']) => {
    const draft = ctx.get(policyDraftAtom);

    policyDraftAtom(ctx, {
      ...draft,
      coverageType,
    });

    const dirtySections = new Set(ctx.get(dirtySectionsAtom));
    dirtySections.add('coverage');
    dirtySectionsAtom(ctx, dirtySections);
  },
  'updateCoverageType',
);

The coverage type change is not just a setter. It changes the draft and marks a section dirty. Later it might clear dependent fields. Later it might add a warning. The action is where that transition belongs.

This is the main reason I like action-based state models. They create names for product events:

• updateCoverageType
• removeBeneficiary
• restoreDraft
• markSectionReviewed
• resetBuilder

Those names are easier to reason about than a trail of setState calls.

React Components Stay Small

The component should read state and dispatch intent.

// src/features/build-policy/ui/CoverageSection.tsx
import { reatomComponent } from '@reatom/npm-react';
import { policyDraftAtom } from '../model/policy-builder.atoms';
import { updateCoverageType } from '../model/policy-builder.actions';

export const CoverageSection = reatomComponent(({ ctx }) => {
  const draft = ctx.spy(policyDraftAtom);

  return (
    <section>
      <h2>Coverage</h2>
      <CoverageTypeSelect
        value={draft.coverageType}
        onChange={(coverageType) => updateCoverageType(ctx, coverageType)}
      />
    </section>
  );
}, 'CoverageSection');

The component does not know how dirty state works. It does not know which dependent values reset. It says: the user changed coverage type.

The model handles the transition.

That separation is the payoff.

Where Reatom Meets TanStack Query

Query loads the server state. Reatom owns the local workflow.

When opening an existing policy builder, seed the draft from Query data:

export function PolicyBuilderRoute({ policyId }: { policyId: string }) {
  const policyQuery = useQuery(policyDetailQueryOptions(policyId));

  if (policyQuery.isPending) return <PolicyBuilderSkeleton />;
  if (policyQuery.isError) return <PolicyBuilderError onRetry={() => policyQuery.refetch()} />;

  return <PolicyBuilderPage initialPolicy={policyQuery.data} />;
}

Then initialize the feature model at the boundary:

export function PolicyBuilderPage({ initialPolicy }: { initialPolicy: PolicyDetail }) {
  const draft = mapPolicyToDraft(initialPolicy);

  return (
    <PolicyBuilderScope initialDraft={draft}>
      <CoverageSection />
      <BeneficiariesSection />
      <ReviewPanel />
    </PolicyBuilderScope>
  );
}

The important boundary: server data becomes an initial draft. After that, the draft is client state.

When the user saves:

export const savePolicyDraft = action(async (ctx) => {
  const draft = ctx.get(policyDraftAtom);

  await updatePolicyDraft(draft);

  dirtySectionsAtom(ctx, new Set());
}, 'savePolicyDraft');

Then invalidate Query data if needed:

queryClient.invalidateQueries({ queryKey: policyKeys.detail(policyId) });

Do not keep the Query cache and draft atom synchronized on every keystroke. That turns two clear models into one blurry model.

Effects Need Discipline

Autosave is a good example.

It is tempting to put autosave in a component:

useEffect(() => {
  const id = setTimeout(() => saveDraft(draft), 1000);
  return () => clearTimeout(id);
}, [draft]);

That works until the component unmounts, remounts, gets split, or the draft changes from somewhere else.

For serious workflows, autosave should live near the state model. It reacts to the model, not to a particular component being mounted.

The exact Reatom effect API depends on setup, but the shape is what matters:

export const autosaveDraft = action(async (ctx) => {
  const draft = ctx.get(policyDraftAtom);
  const hasChanges = ctx.get(hasUnsavedChangesAtom);

  if (!hasChanges) return;

  await savePolicyDraftToServer(draft);
  dirtySectionsAtom(ctx, new Set());
}, 'autosaveDraft');

Then schedule or trigger it from the feature boundary, not from every field.

Effects should be named. Effects should be cancellable when needed. Effects should not hide in five components.

Undo and History

This is where graph-based state starts to feel worth it.

Undo is awkward when state is scattered across components. It is manageable when workflow state has a model.

export const draftHistoryAtom = atom<PolicyDraft[]>([], 'draftHistoryAtom');

export const commitDraftChange = action((ctx, nextDraft: PolicyDraft) => {
  const currentDraft = ctx.get(policyDraftAtom);
  const history = ctx.get(draftHistoryAtom);

  draftHistoryAtom(ctx, [...history, currentDraft]);
  policyDraftAtom(ctx, nextDraft);
}, 'commitDraftChange');

export const undoDraftChange = action((ctx) => {
  const history = ctx.get(draftHistoryAtom);
  const previousDraft = history.at(-1);

  if (!previousDraft) return;

  draftHistoryAtom(ctx, history.slice(0, -1));
  policyDraftAtom(ctx, previousDraft);
}, 'undoDraftChange');

Would I add undo to every form? No.

But when the product needs it, I want the state model to make it boring.

What Not to Put in Reatom

Reatom is not a dumping ground.

Do not put this in Reatom by default:

• fetched server data that belongs in TanStack Query
• simple component booleans
• URL state that belongs in TanStack Router search params
• form field state already owned cleanly by TanStack Form
• one-off UI state that never leaves a component

The fact that a library can hold state does not mean it should hold all state.

My default split:

• TanStack Query: server state
• TanStack Router: URL/navigation state
• TanStack Form: form field state and validation flow
• Reatom: complex client workflows and reactive graphs
• useState: local component details

This split keeps each tool honest.

The Review Checklist

When I review client state, I ask:

• Is this state server-owned, URL-owned, form-owned, or client-owned?
• Can it stay local with useState?
• Is this derived value being stored manually?
• Are components changing atoms directly, or dispatching named actions?
• Does the feature model live near the feature?
• Are effects named and centralized, or hidden in component trees?
• Is Query cache being abused as a local store?
• Can a new developer see the state graph without opening ten components?

The last question matters most. State management is not about reducing lines. It is about making change propagation understandable.

What Comes Next

Reatom gives us a way to model complex client workflows. The next article goes one layer deeper: immutable data structures in React. Not as a purity lecture, but as the practical reason state graphs, memoization, optimistic updates, and undo histories stay predictable.

The policy builder eventually stopped feeling like a form and started feeling like a small application. That was the important realization. Treating it as "just component state" made every requirement feel like an exception. Treating it as a workflow model made the requirements fit somewhere.

Not because Reatom was magic.

Because the state graph finally had a shape.

If you're working on a React feature where every small change triggers three unrelated effects, reach out. The problem may not be your components. It may be that the workflow wants a model of its own.

I recently wrote a detailed article on this topic. It came out long because I wanted to cover every nuance — the full story, detailed interview examples, the AI angle, common mistakes, and practical formats. But I realize not everyone has 15 minutes to spare, so here is the short version covering only the essentials.

The Problem

Experienced engineers fail interviews. Not because they lack skill — because the interview tests the wrong thing.

I have over a decade of production frontend experience. TypeScript, React, enterprise products, design systems, team leadership. And I have failed interviews because I could not recall the exact behavior of Promise.allSettled under pressure or write a tree traversal algorithm from memory. These are things I almost never do by hand in real work.

The trivia-based interview format creates false negatives (rejecting experienced builders who do not drill interview prep) and false positives (passing candidates who memorized answers but cannot make architecture decisions). It tests recall under stress — a scenario that never occurs in actual engineering work.

What Works Instead

Talk to the candidate like a colleague. Ask about real scenarios and follow up on every answer.

The best interview I ever had was with a guy named John at a large Canadian company in the automotive industry. Two hours. No algorithms, no trivia. Just questions like:

• "You inherit a React app with 200+ components and no design system. What is your first week like?"
• "Two teams depend on the same component library but ship on different schedules. How do you handle versioning?"
• "A junior on your team writes overly abstract code. How do you handle that conversation?"

Every answer led to a follow-up: "What if the team pushes back?" "What if the deadline is two weeks?" He was mapping how I think, not checking what I have memorized.

I got the job and stayed for three years. No whiteboard session would have predicted that outcome better.

How Simple Questions Reveal Deep Expertise

You do not need complex scenarios. Start simple and follow the thread.

Example: "Your team needs to support dark mode across the product. How do you approach it?"

A junior talks about CSS variables. A senior asks: "How big is the product? Is there a design system? Does design have dark mode tokens ready? Is this a gradual rollout?" Then follow up: "Design only covers 40% of components — the rest is on you." Then: "A senior dev wants to refactor all CSS first. What do you do?" Then: "Product wants to A/B test with 10% of users."

One question. Fifteen minutes. You see problem decomposition, ambiguity handling, leadership instincts, and technical depth. No algorithm required.

Example: "Users say the app feels slow. No specific page, just... slow. What do you do?"

A senior starts with: "Before I touch code — what does slow mean to users? Initial load? Navigation? Interactions? Do we have metrics? Is it all users or specific segments?" Then you push: "Mainly mobile users on slow networks." Then: "VP wants a fix in two weeks for a board meeting." Then: "Backend says APIs are fine, it is purely frontend."

Two questions. Thirty minutes total. You know how this person operates in the real world.

Ask About AI

In 2026, skipping AI in a senior interview means missing critical signal. Some seniors write ten lines by hand per week and orchestrate AI agents for the rest. Others barely use AI. Both can be effective.

The issue: candidates will not volunteer their AI usage honestly unless you make it safe. There is still stigma.

Ask openly:

• "Walk me through how you built the last feature you shipped — tools, process, everything."
• "When you use AI-generated code, what is your review process?"
• "A developer submits a PR that is entirely AI-generated. They understand it, but did not write it by hand. How do you feel as a reviewer?"

You are evaluating judgment about tools and quality — not whether they use AI.

Where This Breaks

Requires skilled interviewers. You cannot run this from an answer sheet. The interviewer needs domain depth and the ability to improvise follow-ups.

Consistency is hard. Different interviewers, different questions, different evaluations. Shared rubrics and calibration sessions are essential.

Charisma bias. Open conversations favor articulate, sociable candidates. Evaluate substance of answers, not delivery style.

Takes more time. You need 60–90 minutes. This does not work for high-volume initial screening — use it in final rounds.

Common Mistakes

• Having a "correct" answer in your head. You are evaluating reasoning, not checking solutions.
• Being too casual. "Just a chat" produces no signal. You need evaluation criteria.
• Not following up. The first answer is surface level. Push with "why?", "what if?", "what could go wrong?"
• Not calibrating across interviewers. Without shared rubrics, you get incomparable evaluations.
• Treating AI usage as a red flag. The right follow-up to "I use AI for 80% of code" is "how do you ensure quality?" — not a concerned look.

Quick Recommendations

Interviewers: Build 5–8 scenario questions from real team challenges. Write a rubric with clear dimensions (problem decomposition, trade-off awareness, communication, technical depth, collaboration, leadership). Run calibration sessions quarterly. Ask about AI openly.

Candidates: When you do not remember an API detail — say so and explain the concept. Prepare stories about real projects, not rehearsed definitions. Be honest about your AI workflow. Ask your own questions aggressively — they signal seniority more than your answers do. If the interview feels like an exam, that is a signal about the culture.

Summary

Senior interviews should test judgment, not recall. Simple scenario questions with deep follow-ups reveal more about an engineer's real capability than any algorithm or trivia quiz. It takes better interviewers and more time, but you hire people who can actually do the job. In an era where AI handles routine code generation, the quality of decisions is what makes a senior engineer valuable. Test for that.

For the full deep-dive with complete interview formats and extended examples, read the long version.

If you have thoughts on this or want to share your own interview experience — reach out.

I have failed interviews. Multiple times. Not because I did not know my craft — I have been shipping production frontend for well over a decade. I failed because I could not recite the exact behavior of Promise.allSettled under pressure, or because I blanked on a tree traversal algorithm I had not hand-written since university. Meanwhile, the things I actually do every day — making architecture decisions, untangling legacy code, mentoring developers, designing systems that survive contact with real users — none of that was being tested.

This article is about what a good senior interview looks like. I know because I experienced one, and it changed everything.

Context: The Interview Problem Nobody Talks About

There is an uncomfortable truth in our industry. Many experienced engineers — people who have built and maintained complex production systems for years — routinely fail technical interviews.

Not because they are bad engineers. Because the interview tests a different skill than the job requires.

I work primarily with TypeScript and React. Promises? I use them every day — through async/await, through React Query, through framework abstractions. But when someone puts me in front of a whiteboard and says "chain three promises, handle partial failures, and explain the microtask queue," I stumble. Not because I do not understand the concept. Because I do not carry that specific API surface in my active memory. I have not needed to.

Tree traversals and graph algorithms? Honestly — I do not enjoy them and I rarely encounter them in my daily work. When I need something like that, I reach for a library or write a straightforward recursive approach. I do not sit and think about BFS vs DFS complexity tradeoffs while building a dashboard for an enterprise client.

Logical puzzles? Same story. I can solve them given time and a calm environment. Under interview pressure, with someone watching me and a timer ticking? I freeze. And I know I am not alone.

Here is what bothers me most: I have seen engineers who drill LeetCode for months pass these interviews with flying colors, then struggle to make a single meaningful architecture decision in their first sprint. The interview selected for the wrong thing. It tested preparation discipline, not engineering capability.

I am not saying algorithmic knowledge is useless. I am saying that for a senior role, it should not be the primary filter. And yet — at most companies — it still is.

The Interview with John

Let me tell you about the best technical interview I have ever experienced.

It was at a large Canadian company. Well-known products — automotive industry. The kind of place where the frontend work is complex, the user base is massive, and the decisions you make on Monday are still affecting the product two years later.

My interviewer was John. I remember his name because what happened in that interview stuck with me permanently. I still feel a kind of gratitude toward him years later — not because he went easy on me, but because he showed me what a respectful, effective technical interview looks like.

We were scheduled for ninety minutes. We went over two hours. I did not notice the time passing. Not once did I feel like I was being tested. It felt like I was having a deep technical conversation with a colleague I respected.

John did not ask me what a closure is. He did not ask me to reverse a linked list. He did not ask me to explain the event loop.

Instead, he asked things like:

• "You join a team and inherit a React app with 200+ components and no design system. What is your first week like?"
• "The product team wants to support three different brands from the same codebase. How would you approach the frontend?"
• "You notice the CI pipeline takes 40 minutes and developers are complaining. Where do you start?"
• "Two teams depend on the same component library but ship on different schedules. How would you handle versioning?"
• "A junior on your team writes overly abstract code — creates a generic wrapper for everything. How do you handle that conversation?"

Every answer I gave led somewhere. John would nod and then say, "Okay, but what if the team pushes back on that approach?" or "What if the deadline is in two weeks?" or "What happens when the third team joins and they use a different state management solution?" He was not looking for a specific answer. He was mapping how I think.

I got the job. I stayed for about three years. The team was strong, the work was meaningful, and as far as I could tell, the company did not regret the hire. That interview — with no algorithms, no trivia, no trick questions — predicted my actual job performance far better than any whiteboard session ever could.

That experience left me with a conviction: you learn more about a senior engineer in thirty minutes of genuine conversation than in two hours of trivia.

Why Trivia-Based Senior Interviews Are Fundamentally Broken

Let me be specific about the failure modes.

The wrong skill is being tested. When you ask a senior engineer to write a debounce function from memory, you are testing recall. But a senior's actual value lies in knowing when to debounce, where it matters for user experience, and whether the framework already provides a better abstraction. The API signature is a Google search away. The judgment is not.

False negatives destroy your pipeline. The most experienced candidates — the ones who have been building real systems instead of doing interview prep — are the ones most likely to fail trivia questions. They have been too busy shipping code to memorize it. You are systematically filtering out the people you want most.

False positives are expensive. A candidate who spent three months on an interview prep platform will ace your quiz. They might know every closure edge case, every prototype chain gotcha, every this binding trap. But put them in front of a real architecture decision — "should we build a micro-frontend or keep the monolith?" — and they might have nothing to say. That mismatch costs you months of onboarding and potentially a bad hire.

Stress is not signal. There is a pervasive belief that "if they can perform under pressure, they will be good in production." This is wrong. Interview stress and production pressure are fundamentally different experiences. In production, you have context, tools, colleagues, and time to think. In an interview, you have a stranger staring at you while you try to remember if Array.prototype.flat takes a depth argument. These are not comparable situations. You are measuring anxiety tolerance, not engineering skill.

It does not match how we actually work. In my daily work, I look things up constantly. I read documentation. I discuss approaches in Slack. I use AI to scaffold boilerplate. I do code reviews where I catch things I would not have remembered in an interview. The isolated, no-tools, no-references interview environment tests a scenario that literally never occurs in the actual job.

The Conversational Interview: What It Looks Like in Practice

The alternative is not "just chatting." A conversational interview has structure, evaluation criteria, and clear goals. But it evaluates what matters: how the candidate thinks about problems, makes decisions, and handles complexity.

Let me walk through two complete examples. These are realistic — the kind of conversations you could have with a senior frontend candidate next week.

Example 1: The Innocent Question That Reveals Everything

Imagine you start the interview with this:

"Hey, so — your team has just been told that you need to support dark mode across the entire product. How do you approach this?"

This sounds almost too simple. Dark mode. Every junior knows about prefers-color-scheme. But this question is a depth charge. Watch what happens when you follow the thread.

A junior will talk about CSS variables and a toggle button. A mid-level will mention design tokens, maybe theming with styled-components or Tailwind.

A senior? A senior will start asking questions back:

• "How big is the product? How many pages, how many components?"
• "Is there a design system, or are styles scattered?"
• "Does the design team have dark mode designs ready, or are we deriving them?"
• "What is the CSS architecture — utility-first, CSS modules, CSS-in-JS?"
• "Are there third-party components that do not support theming?"
• "Is this a gradual rollout or a big-bang release?"

Now you are in a real conversation. Follow up with:

• "The design team says they will provide dark mode tokens, but only for the core components. The rest — about 60% of the UI — you have to figure out." This tests whether they can handle ambiguity and make pragmatic decisions about imperfect situations.

• "One of the senior developers on the team insists on doing a full CSS refactor before implementing dark mode. He says the current styles are too messy. What do you do?" This is no longer a technical question — it is a leadership and collaboration question. How do they handle disagreement? Do they see the tradeoff between ideal and practical?

• "Product says they want to A/B test dark mode with 10% of users first." Now you are in feature flags, runtime theming, and state management territory. Do they think about persistence? Server-side rendering? Flash of unstyled content?

One question. Fifteen minutes. You have learned more about this person's seniority than any algorithm challenge could reveal. You have seen how they decompose problems, how they handle incomplete information, how they think about people and process alongside code.

Example 2: The Deceptively Simple Scenario

Here is another one:

"A product manager comes to you and says: users are complaining that the app feels slow. No specific page, just... slow. What do you do?"

Again — sounds easy. But a senior engineer's answer to this question reveals an enormous amount about their experience.

The junior answer: "I would use Lighthouse and fix the scores."

The mid-level answer: "I would profile the app, check bundle size, look at network requests."

The senior answer starts with: "Before I touch any code, I need to understand what 'slow' means to the users."

• "Is it initial load time? Navigation between pages? Interaction responsiveness? All of the above?"
• "Do we have any metrics — Core Web Vitals, custom performance tracking, session recordings?"
• "Is it slow for all users or specific segments — mobile, specific regions, specific browsers?"
• "When did it start feeling slow? Was there a recent deployment that correlates?"

Follow up:

• "Turns out it is mainly mobile users in regions with slower networks. Desktop users are fine." This pushes toward real-world constraints — code splitting, server-side rendering, image optimization, CDN strategy. Do they think about the network layer, or only about JavaScript?

• "The VP of Engineering wants a fix in two weeks because there is a board meeting." Now you are testing prioritization under pressure. Do they panic and promise everything? Do they push back with data? Do they suggest a phased approach — quick wins first, structural changes later?

• "The backend team says the APIs are fine and the problem is purely on the frontend." How do they handle cross-team accountability? Do they accept that at face value, or do they know how to prove or disprove it with data?

Two questions. Two conversations. Thirty minutes total. You now have a detailed picture of how this person operates in the real world. You know their technical depth, their communication style, their leadership instincts, and their ability to work with ambiguity. No whiteboard required.

What Makes These Questions Work

Notice what both examples have in common:

• The initial question is approachable. It does not trigger "I need to remember the right answer" anxiety. It triggers "let me think about this problem."
• Depth comes from follow-ups, not from the question itself. The interviewer's skill matters. You need to know where to push.
• There is no single correct answer. Multiple good approaches exist. What you evaluate is reasoning, awareness of tradeoffs, and the ability to adapt when the situation changes.
• They test real-world skills. Ambiguity handling, stakeholder management, prioritization, team dynamics — these are what senior engineers actually deal with every day.

The AI Question Every Senior Interview Needs in 2026

Let me say something that might be controversial: if you are interviewing a senior engineer in 2026 and you do not ask about AI, you are missing a critical data point.

Here is the reality. I know engineers — good ones, experienced ones — who write maybe ten lines of code by hand per week. The rest is orchestrating AI agents. They prompt, they review, they refine, they iterate. And they are productive. They ship features, maintain quality, and make good architectural decisions. They are still seniors — arguably more effective seniors than before.

I also know engineers who barely use AI. They write everything by hand, they are meticulous, and they produce excellent work. Also valid.

The interesting question is not "do you use AI?" It is everything that comes after.

But here is the problem: candidates will not talk about this honestly unless you make it safe. There is still a stigma. Engineers worry that admitting heavy AI usage will make them look lazy or less skilled. So they downplay it. And you miss the real picture.

How to ask:

• "Walk me through how you built the last feature you shipped. Tools, process, everything." This is open-ended enough that they can naturally mention AI without feeling judged.
• "When you use AI-generated code, what is your review process? What do you look for?" This tells you whether they are using AI thoughtfully or blindly.
• "Have you seen AI-generated code cause a problem in production? What happened?" A senior who uses AI regularly will have a story. And how they handled it tells you about their quality standards.
• "A developer on your team submits a PR that is entirely AI-generated. They understand it, but they did not write any of it by hand. How do you feel about that as a reviewer?" This tests their philosophy about code ownership, maintainability, and team standards.

What you are really evaluating is judgment. Does this person use AI as a power tool while maintaining engineering responsibility? Or are they outsourcing their thinking? There is a big difference, and a conversational interview is the only format that can surface it.

Where Conversational Interviews Break Down

I am not going to pretend this approach is perfect. It has real limitations.

It requires skilled interviewers. Running a conversational interview well is hard. You need someone who knows the domain deeply enough to improvise follow-ups, challenge weak answers, and recognize strong ones even when they differ from what they expected. A trivia quiz can be run by anyone with an answer sheet. A conversational interview needs a senior engineer who is also a good communicator. Not every team has that.

Consistency is genuinely difficult. When different interviewers ask different questions in different ways, comparing candidates becomes harder. Two candidates might both be strong, but the scores look different because one interviewer went deep on architecture while another focused on team dynamics. You need a shared rubric with explicit evaluation dimensions to mitigate this.

It takes more time. A meaningful conversational interview needs 60 to 90 minutes. You cannot rush it to 30. For companies doing high-volume hiring, that is a real constraint.

Charisma bias is a real risk. Open-ended conversations naturally favor people who are articulate, confident, and personable. Brilliant engineers who are introverted, or who communicate better in writing than in speech, or who think slowly and carefully, can get undervalued. Your rubric needs to account for this — evaluate the substance of answers, not the delivery.

Some candidates genuinely prefer structured tests. Not everyone thrives in ambiguity. Some great engineers feel more comfortable with a clear problem, a clear solution, and a clear evaluation. Dismissing their preference entirely is its own form of bias.

Common Mistakes When Running Conversational Interviews

Asking scenario questions but having a "correct" answer in your head. If you already decided that the right approach to the dark mode question is "use CSS custom properties with a ThemeProvider," you are just running trivia with extra steps. The goal is to evaluate reasoning, not to check if they chose the same solution you would.

Being too casual. "Let's just chat" produces zero usable signal. You need a plan: which scenarios, which follow-ups, what evaluation criteria. The conversation should feel informal. The evaluation should be rigorous.

Not going deep enough. The first answer to any question is the surface layer. The signal is in the second and third follow-ups. "Why that approach?" "What could go wrong?" "What would you do differently with more time?" If you accept the first answer and move on, you are wasting the format.

Failing to calibrate. Three interviewers running three different conversational interviews without shared criteria will produce three incomparable evaluations and an argument in the debrief meeting. Calibration sessions — where interviewers evaluate the same recorded interview and compare notes — are not optional.

Testing outside the candidate's experience. If someone has spent their career in React and you ask them to design a distributed backend system, you will get a weak answer that tells you nothing. Tailor your scenarios to the role and the candidate's actual background.

Treating AI usage as a negative signal. This one deserves its own bullet point because it is still happening everywhere. If a candidate openly says "I use AI for 80% of my initial code generation," the correct follow-up is "how do you ensure quality and maintainability?" Not a raised eyebrow.

When NOT To Use Conversational Interviews

This format works best for senior, staff, and principal-level roles where judgment, systems thinking, and leadership matter more than implementation speed.

For junior roles, you need to verify fundamental skills. A coding exercise — even a simple one — is reasonable. You need to know they can write a function, debug an error, use basic data structures. A conversational interview would not produce enough signal at this level because junior candidates might not have enough experience to discuss.

For mid-level roles, a hybrid works well. A short practical task — maybe a small feature implementation or a debugging exercise — followed by a conversational segment about their approach and decisions.

For high-volume pipelines processing hundreds of applicants per week, conversational interviews do not work for initial screening. Use them in final rounds where signal quality matters most and the candidate pool is already filtered.

And if you honestly cannot train your interviewers to run these well — if they will default to "just chatting" without structure or evaluation criteria — then a structured technical assessment with a clear rubric will give you more consistent, if less insightful, results. A mediocre conversational interview is worse than a well-run structured one.

How I Apply This

When I interview senior candidates now, the first thing I say is: "This is not a test. I want to understand how you think about problems." You can visibly see people relax. The dynamic shifts from "exam" to "conversation." And that shift is where the good signal lives.

I pick two or three scenarios from projects I have actually worked on — problems where I already know the trade-offs, the failure modes, the "it depends" factors. This lets me push on follow-ups authentically instead of working from a script.

I pay close attention to how candidates handle what they do not know. Do they acknowledge the gap and think through it? Do they ask clarifying questions? Do they try to bluff? That single behavioral signal — comfort with uncertainty — correlates more strongly with real-world senior performance than any technical test I have seen.

I always ask about AI. Always. The answer tells me whether they are adapting to how our craft is evolving or clinging to how it used to be. Both types of engineers can be effective, but I want to know which one I am hiring.

The best senior hires I have been part of all came through conversational interviews. The worst mismatch I ever witnessed was someone who aced every technical quiz but could not have a productive discussion about trade-offs in their first sprint. They knew all the answers. They just could not apply them to real problems.

Practical Recommendations

If you are an interviewer or hiring manager:

• Build a library of 5–8 scenario questions drawn from real challenges your team has faced. Rotate them across interviews.
• Write a rubric with clear dimensions: problem decomposition, trade-off awareness, communication clarity, technical depth, collaboration instincts, leadership signal. Score each dimension independently.
• Run calibration sessions at least quarterly. Have two or three interviewers evaluate the same mock candidate (or a recorded session) and compare scores. Discuss disagreements.
• Let interviews run long if the conversation is productive. Cutting off a great discussion at exactly 60 minutes because the calendar says so is counterproductive.
• Ask about AI openly. Normalize it. The candidates who are honest about their AI workflow are giving you more useful information than those who claim they write everything by hand.

If you are a candidate:

• When you do not remember an exact API or detail — say so, explain the concept, and describe how you would find it. This is what you would do at work. A good interviewer will not hold it against you. A bad one will, and that tells you something about the company.
• Prepare stories, not answers. Think about real projects: problems you encountered, decisions you made, trade-offs you accepted, things you would do differently. Stories are memorable and specific. Rehearsed definitions are not.
• Be honest about your AI workflow. If you use Copilot, Cursor, Claude, or any other tool heavily — own it. Explain how you review, validate, and maintain what gets generated. Hiding your actual workflow means the company is evaluating a version of you that does not exist.
• Pay attention to how you are being interviewed. If it feels like a university exam — question after question, right or wrong, no discussion — that is a signal about the engineering culture. Use that information when you decide whether to accept or decline.
• Ask your own questions aggressively. What is the team's architecture like? How are decisions made? What was the last big technical bet that did not work out? Your questions reveal your seniority more than your answers do.

Summary

The best technical interview I ever had involved zero algorithms, zero API trivia, and zero whiteboard coding. It was a two-hour conversation with a guy named John at a large Canadian automotive company, where he asked me real questions about real problems and followed every answer with "what if?" I learned more about how interviews should work from that single experience than from dozens of standard ones on both sides of the table.

Senior interviews should test judgment. They should surface how a candidate thinks about ambiguity, trade-offs, team dynamics, and the realities of production systems. Conversational formats — scenario-based discussions, simple-sounding questions with deep follow-ups, collaborative problem-solving — do this better than any quiz.

They require better interviewers. They require shared rubrics and calibration. They take more time. But the trade-off is clear: you hire people who can actually do the job, not just people who can pass the test.

In an era where AI writes a significant chunk of our code, the thing that makes a senior engineer valuable is not what they can recite from memory. It is the quality of the decisions they make. Test for that.

If you have thoughts on how senior interviews should work — or horror stories from the other side — I'd love to hear them.

The policy list bug started as a support ticket.

An agent filtered policies by status, page, and renewal date. She copied the URL and sent it to another agent. The second agent opened it and saw a different list.

Same page. Same product. Different state.

The filters were not in the URL. The page number lived in local component state. The selected tab lived in a store. The search box was debounced into a fetch call, but never synchronized back to navigation. The route looked shareable. It wasn't.

Honestly, that bug changed how I think about routing.

Routing is not just "which component renders for this path." That is the small version. In product software, routing is about preserving intent. What screen is the user on? Which record? Which filters? Which tab? Which page? Can they reload and get the same view? Can they send the link to someone else and trust it?

I've seen teams treat the URL as decoration. Then they spend months rebuilding browser behavior manually.

TanStack Router gives React apps a better option: typed routes, typed params, typed search, loaders, redirects, preloading, and integration with TanStack Query. The point is not fancy routing. The point is making navigation state explicit.

A URL is not a string you push into history. It is part of your application's state model.

This is article #6 in the React Playbook series. We already covered the stack, TypeScript patterns, code structure, error handling, and TanStack Query. Now we connect those pieces through routing.

Why TanStack Router

React Router is familiar. It works. I used it for years.

The reason I reach for TanStack Router in new TypeScript-heavy apps is not that React Router is bad. It is that TanStack Router makes more route mistakes impossible.

With TanStack Router, routes are registered into a typed route tree. That means:

• <Link to="/policies/$policyId"> knows which params are required.
• useParams({ from: '/policies/$policyId' }) returns the right param type.
• useSearch({ from: '/policies' }) returns validated search state.
• navigate({ to, params, search }) is checked against the actual route.
• Loaders can use route context and params safely.

The difference is subtle until a route changes.

Rename $policyId to $id, and TypeScript tells you everywhere the old param is still used. Remove a search param, and navigation calls fail to compile. That is the kind of friction I want.

Not because I enjoy types for their own sake.

Because broken links and stale URL assumptions are production bugs.

File-Based or Code-Based Routes?

TanStack Router supports both file-based and code-based routing.

For large teams, I like file-based routing. It creates a predictable structure, works well with route code splitting, and keeps route files close to pages.

For teaching and small early projects, code-based routing is easier to see in one place.

This article uses a file-based shape because it is what I would use once the app grows:

src/
  routes/
    __root.tsx
    index.tsx
    policies/
      index.tsx
      $policyId.tsx
      $policyId.edit.tsx
  routeTree.gen.ts

In an FSD-style project, I still keep page UI in pages/ and let route files wire it:

src/
  routes/
    policies/
      index.tsx
      $policyId.tsx
  pages/
    policy-list/
      PolicyListPage.tsx
    policy-detail/
      PolicyDetailPage.tsx

Route files are integration points. They connect URL shape, loader behavior, search validation, and page components. They should not become business logic containers.

The Root Route

The root route is where app-level layout and route context begin.

// src/routes/__root.tsx
import { Outlet, createRootRouteWithContext } from '@tanstack/react-router';
import type { QueryClient } from '@tanstack/react-query';
import { RootLayout } from '@/app/RootLayout';

interface RouterContext {
  queryClient: QueryClient;
  auth: AuthSession | null;
}

export const Route = createRootRouteWithContext<RouterContext>()({
  component: RootRoute,
});

function RootRoute() {
  return (
    <RootLayout>
      <Outlet />
    </RootLayout>
  );
}

That context matters. Later, route loaders can access queryClient without importing a singleton. Auth checks can use the current session. Tests can provide a different context.

Then create the router:

// src/app/router.ts
import { createRouter } from '@tanstack/react-router';
import { routeTree } from '@/routeTree.gen';
import { queryClient } from './query-client';
import { authSession } from './auth-session';

export const router = createRouter({
  routeTree,
  context: {
    queryClient,
    auth: authSession,
  },
});

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router;
  }
}

The Register declaration is the bridge that gives the rest of the app type-safe navigation. Skip it and you lose much of the point.

Route Params Should Be Boring

A policy detail route:

// src/routes/policies/$policyId.tsx
import { createFileRoute } from '@tanstack/react-router';
import { PolicyDetailPage } from '@/pages/policy-detail';

export const Route = createFileRoute('/policies/$policyId')({
  component: PolicyDetailRoute,
});

function PolicyDetailRoute() {
  const { policyId } = Route.useParams();

  return <PolicyDetailPage policyId={policyId} />;
}

policyId is typed from the route path. No manual generic. No as string. No "I hope this param exists."

Navigation is typed too:

import { Link } from '@tanstack/react-router';

export function PolicyRow({ policy }: { policy: Policy }) {
  return (
    <Link to="/policies/$policyId" params={{ policyId: policy.id }}>
      {policy.policyNumber}
    </Link>
  );
}

If you forget policyId), TypeScript complains. If you pass idinstead ofpolicyId`, TypeScript complains. That is boring in the best possible way.

Search Params Are Product State

The policy list route is where TanStack Router starts to feel different.

Filters belong in the URL:

/policies?status=active&page=2&query=miller

Not because URLs are pretty. Because users reload pages, bookmark views, share links, and go back in browser history.

Define the search shape:

// src/routes/policies/index.tsx
import { createFileRoute } from '@tanstack/react-router';
import { z } from 'zod';
import { PolicyListPage } from '@/pages/policy-list';

const policyListSearchSchema = z.object({
  status: z.enum(['active', 'expired', 'pending']).optional(),
  page: z.number().int().positive().catch(1),
  query: z.string().catch(''),
});

export const Route = createFileRoute('/policies/')({
  validateSearch: policyListSearchSchema,
  component: PolicyListRoute,
});

function PolicyListRoute() {
  const search = Route.useSearch();

  return <PolicyListPage filters={search} />;
}

Now search.page is a number. Not a string you parsed manually. Not string | undefined. A number.

This matters because search params are the easiest place for type lies to enter an app. The browser gives you strings. Your product wants domain state. TanStack Router gives you a validation boundary.

Updating Search Without Losing State

When the user changes a filter:

import { useNavigate } from '@tanstack/react-router';

export function PolicyFilters({ filters }: { filters: PolicyListFilters }) {
  const navigate = useNavigate({ from: '/policies/' });

  return (
    <StatusSelect
      value={filters.status}
      onChange={(status) => {
        navigate({
          search: (prev) => ({
            ...prev,
            status,
            page: 1,
          }),
        });
      }}
    />
  );
}

Notice the page: 1.

Changing status should reset pagination. This is a product rule. Put it where navigation state changes. Otherwise you end up on page 7 of a filter that only has one page and someone files a "missing policies" bug.

For pagination:

export function PolicyPagination({ page }: { page: number }) {
  const navigate = useNavigate({ from: '/policies/' });

  return (
    <Pagination
      page={page}
      onPageChange={(nextPage) => {
        navigate({
          search: (prev) => ({
            ...prev,
            page: nextPage,
          }),
        });
      }}
    />
  );
}

No local useState. The URL is the state.

Connecting Router to Query

Article #5 covered query options. Routing is where they pay off.

// src/routes/policies/index.tsx
export const Route = createFileRoute('/policies/')({
  validateSearch: policyListSearchSchema,
  loaderDeps: ({ search }) => ({ search }),
  loader: ({ context, deps }) =>
    context.queryClient.ensureQueryData(policiesQueryOptions(deps.search)),
  component: PolicyListRoute,
});

The route validates search. The loader uses validated search to warm the query cache. The page subscribes to the same query:

function PolicyListRoute() {
  const search = Route.useSearch();
  const policiesQuery = useQuery(policiesQueryOptions(search));

  return <PolicyListPage filters={search} policiesQuery={policiesQuery} />;
}

One data definition. Two usages.

That is the shape I want: route loaders handle navigation-level data readiness; components still use Query for cache subscription, background refetching, and UI state.

Don't fetch in the loader and pass raw data into the component while also using Query elsewhere. That creates two data paths. Use the loader to fill the cache.

Detail Routes and Not Found

For detail pages:

// src/routes/policies/$policyId.tsx
import { createFileRoute, notFound } from '@tanstack/react-router';
import { policyDetailQueryOptions } from '@/entities/policy';
import { isNotFoundError } from '@/shared/api';
import { PolicyDetailPage } from '@/pages/policy-detail';

export const Route = createFileRoute('/policies/$policyId')({
  loader: async ({ context, params }) => {
    try {
      return await context.queryClient.ensureQueryData(
        policyDetailQueryOptions(params.policyId),
      );
    } catch (error) {
      if (isNotFoundError(error)) throw notFound();
      throw error;
    }
  },
  component: PolicyDetailRoute,
  notFoundComponent: PolicyNotFound,
  errorComponent: PolicyRouteError,
});

function PolicyDetailRoute() {
  const { policyId } = Route.useParams();
  const policyQuery = useQuery(policyDetailQueryOptions(policyId));

  return <PolicyDetailPage policy={policyQuery.data} />;
}

The route decides whether the page can exist. A missing policy is not the same as a temporary server failure. This lines up with the error-handling model from article #4.

Route Guards with beforeLoad

Some routes require authentication or permissions.

Use beforeLoad for route-level guards:

// src/routes/admin.tsx
import { createFileRoute, redirect } from '@tanstack/react-router';
import { AdminPage } from '@/pages/admin';

export const Route = createFileRoute('/admin')({
  beforeLoad: ({ context, location }) => {
    if (!context.auth) {
      throw redirect({
        to: '/login',
        search: {
          redirectTo: location.href,
        },
      });
    }

    if (context.auth.role !== 'admin') {
      throw redirect({ to: '/policies' });
    }
  },
  component: AdminPage,
});

This is not a replacement for backend authorization. Never trust the frontend for security.

But it is the right place to keep users out of UI they cannot use. It also preserves intent: after login, send them back to where they tried to go.

Preloading on Intent

Routing should feel instant when intent is clear.

TanStack Router can preload routes through links. TanStack Query can prefetch query data. Use both deliberately.

export function PolicyRow({ policy }: { policy: Policy }) {
  return (
    <Link
      to="/policies/$policyId"
      params={{ policyId: policy.id }}
      preload="intent"
    >
      {policy.policyNumber}
    </Link>
  );
}

When the user hovers or focuses the link, the router can prepare the destination. If your route loader calls ensureQueryData, the query cache warms too.

That is the clean integration: link intent -> route preload -> loader -> query cache.

The user clicks, and the page is already halfway there.

Use Route APIs Inside Route Components

TanStack Router gives each route a Route object. Use it.

function PolicyListRoute() {
  const search = Route.useSearch();
  const navigate = Route.useNavigate();

  // ...
}

This is more precise than global hooks when you know which route you are in. The types are anchored to that route. Refactors stay local.

In leaf page components, I still prefer passing explicit props:

function PolicyListRoute() {
  const search = Route.useSearch();
  const policiesQuery = useQuery(policiesQueryOptions(search));

  return <PolicyListPage filters={search} policiesQuery={policiesQuery} />;
}

Why not let PolicyListPage call Route.useSearch() directly?

Sometimes that is fine. But I like keeping page components easier to test and less coupled to router internals. The route knows about routing. The page knows about rendering the product view.

Don't Hide Navigation in Random Helpers

One pattern I avoid:

export function openPolicy(policyId: string) {
  router.navigate({ to: '/policies/$policyId', params: { policyId } });
}

It looks convenient. It spreads navigation decisions into random helpers. Over time, you get hidden redirects, surprising history behavior, and navigation that bypasses route-local search state.

Prefer explicit links and route-local navigation. If a navigation pattern repeats, create a component:

export function PolicyLink({
  policyId,
  children,
}: {
  policyId: string;
  children: React.ReactNode;
}) {
  return (
    <Link to="/policies/$policyId" params={{ policyId }} preload="intent">
      {children}
    </Link>
  );
}

Now navigation stays visible in the UI tree.

The Review Checklist

When I review routing code, I ask:

• Is shareable product state in the URL?
• Are search params validated at the route boundary?
• Do search changes preserve or reset related state intentionally?
• Do route loaders reuse TanStack Query options instead of inventing separate fetch paths?
• Are detail routes handling not-found separately from server errors?
• Are protected routes guarded in beforeLoad?
• Are links using typed to, params, and search instead of string concatenation?
• Is preloading used where user intent is clear?
• Are page components receiving explicit props when that keeps them easier to test?

Most routing bugs are not about paths. They are about state that should have been in the URL but wasn't.

What Comes Next

With Query and Router in place, the next question is client state: the data that does not live on the server but still becomes too complex for useState.

Article #7: state management with Reatom — why I use it in CRM-scale React apps, where it fits next to TanStack Query, and why I don't reach for Zustand by default in this particular stack.

After the policy-list support ticket, we moved filters, page, and search into route search params. The bug disappeared. More importantly, the product started behaving like a web app again. Refresh worked. Back worked. Shared links worked. QA could send exact states to developers instead of screenshots and vague reproduction steps.

That is what routing should do.

Not just render components.

Preserve intent.

If your React app has pages that look shareable but aren't, start with the URL. The fix is often not another store. It is admitting that the route already owns more state than your code says it does.

Three months into the insurance CRM, we had a page that felt haunted.

The policy list would load. Then it would blink. Then it would refetch after switching tabs. Then a status change would update one row but leave another count stale. Sometimes the detail page showed fresh data. Sometimes it showed yesterday's version until someone manually refreshed the browser.

Nobody had written obviously bad code.

There was a useEffect here, a loading boolean there, a bit of local state for filters, a manual refetch after save, and a few defensive checks around undefined data. Each decision made sense in isolation. Together, they formed the kind of frontend state machine nobody wants to debug.

I've seen this pattern more times than I can count. Teams think their data-fetching problem is "how do we call the API?" That is the easy part. The real problem is ownership: who decides whether data is fresh, where it is cached, what invalidates it, what happens during pagination, and what the user sees while the network is moving.

That is why TanStack Query matters.

Not because it fetches.

Because it gives server state a home.

The hardest part of data fetching is not the request. It is the lifecycle around the request.

This is article #5 in the React Playbook series. We already covered the starting stack, TypeScript patterns, code structure, and error handling. Now we get to the layer that makes most React apps feel either calm or twitchy: TanStack Query.

Server State Is Not Client State

The first mental shift is simple but important.

Server state is not yours.

It lives somewhere else. It can change without your app knowing. It can be stale. It can fail. It can be shared by multiple users. It has a network boundary, a cache lifetime, and a synchronization problem.

Client state is different. A dialog is open or closed. A sidebar is collapsed. A draft field has local input. That state belongs to the browser session.

The mistake is mixing the two.

const [policies, setPolicies] = useState<Policy[]>([]);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<Error | null>(null);

useEffect(() => {
  setIsLoading(true);

  fetchPolicies()
    .then(setPolicies)
    .catch(setError)
    .finally(() => setIsLoading(false));
}, []);

This looks harmless. It is fine for a demo. In production, it immediately raises questions:

• What happens when another component needs the same policies?
• How long is this data fresh?
• Who retries?
• Who cancels the request if the component unmounts?
• What invalidates this list after a mutation?
• What happens when filters change?
• What happens when the user leaves and comes back?

You can answer all of those manually. You can also spend the next year rediscovering why caching is hard.

TanStack Query is the place where those answers live.

Start with Query Options, Not Custom Hooks Everywhere

My default pattern in larger apps is to define query options at the entity boundary.

// src/entities/policy/api/policy.queries.ts
import { queryOptions } from '@tanstack/react-query';
import { fetchPolicies, fetchPolicyById } from './policy.api';
import type { PolicyListFilters } from '../model/policy.types';

export const policyKeys = {
  all: ['policies'] as const,
  lists: () => [...policyKeys.all, 'list'] as const,
  list: (filters: PolicyListFilters) => [...policyKeys.lists(), filters] as const,
  details: () => [...policyKeys.all, 'detail'] as const,
  detail: (policyId: string) => [...policyKeys.details(), policyId] as const,
};

export function policiesQueryOptions(filters: PolicyListFilters) {
  return queryOptions({
    queryKey: policyKeys.list(filters),
    queryFn: () => fetchPolicies(filters),
    staleTime: 1000 * 60 * 2,
  });
}

export function policyDetailQueryOptions(policyId: string) {
  return queryOptions({
    queryKey: policyKeys.detail(policyId),
    queryFn: () => fetchPolicyById(policyId),
    staleTime: 1000 * 60 * 5,
  });
}

Then components use the options:

// src/pages/policy-list/PolicyListPage.tsx
import { useQuery } from '@tanstack/react-query';
import { policiesQueryOptions } from '@/entities/policy';

export function PolicyListPage() {
  const filters = usePolicyListFilters();
  const policiesQuery = useQuery(policiesQueryOptions(filters));

  if (policiesQuery.isPending) return <PolicyListSkeleton />;
  if (policiesQuery.isError) return <PolicyListError onRetry={() => policiesQuery.refetch()} />;

  return <PolicyTable policies={policiesQuery.data.items} />;
}

Why not just create usePoliciesQuery(filters)?

Sometimes I do. But query options compose better. The same object can be used by useQuery, route loaders, prefetching, tests, and invalidation helpers. It keeps the query definition in one place without forcing every usage through a hook.

The hook becomes optional sugar, not the source of truth.

Query Keys Are Architecture

Query keys look like small arrays. They are not small.

They are the identity of your server state.

If your keys are inconsistent, invalidation becomes guesswork:

useQuery({ queryKey: ['policy', policyId], queryFn: ... });
useQuery({ queryKey: ['policies', 'detail', id], queryFn: ... });
queryClient.invalidateQueries({ queryKey: ['policy'] });

This is how stale UI survives after a successful mutation.

Use factories:

export const policyKeys = {
  all: ['policies'] as const,
  lists: () => [...policyKeys.all, 'list'] as const,
  list: (filters: PolicyListFilters) => [...policyKeys.lists(), filters] as const,
  details: () => [...policyKeys.all, 'detail'] as const,
  detail: (policyId: string) => [...policyKeys.details(), policyId] as const,
};

This gives you hierarchy:

queryClient.invalidateQueries({ queryKey: policyKeys.lists() });
queryClient.invalidateQueries({ queryKey: policyKeys.detail(policyId) });
queryClient.invalidateQueries({ queryKey: policyKeys.all });

Invalidate all policies. Or only lists. Or one detail. The key shape makes the choice explicit.

The rule is straightforward:

If a variable changes what the query fetches, that variable belongs in the query key.

Filters, page number, cursor, search term, sort order, preview mode, tenant id. Put them in the key. TanStack Query cannot cache what you do not identify.

Freshness Is a Product Decision

TanStack Query's defaults are intentionally active: cached data is stale by default, stale queries refetch on mount, window focus, and reconnect, and inactive queries are garbage-collected after a default cache window.

Those defaults are good for learning and safe for many apps. They are not a substitute for product thinking.

In a CRM, different data has different freshness needs.

export function policyDetailQueryOptions(policyId: string) {
  return queryOptions({
    queryKey: policyKeys.detail(policyId),
    queryFn: () => fetchPolicyById(policyId),
    staleTime: 1000 * 60 * 5,
  });
}

export function policyActivityQueryOptions(policyId: string) {
  return queryOptions({
    queryKey: [...policyKeys.detail(policyId), 'activity'],
    queryFn: () => fetchPolicyActivity(policyId),
    staleTime: 1000 * 30,
  });
}

export function coverageTypesQueryOptions() {
  return queryOptions({
    queryKey: ['coverage-types'],
    queryFn: fetchCoverageTypes,
    staleTime: 1000 * 60 * 60,
    gcTime: 1000 * 60 * 60,
  });
}

Policy detail can be fresh for five minutes. Activity should refresh more aggressively. Coverage types barely change during a session.

This is the kind of decision I want visible in code. If every query inherits one global staleTime, you are pretending all data has the same volatility.

It doesn't.

Background Fetching Without UI Jank

One of TanStack Query's best features is that it separates initial loading from background fetching.

export function PolicyListPage() {
  const filters = usePolicyListFilters();
  const policiesQuery = useQuery(policiesQueryOptions(filters));

  if (policiesQuery.isPending) return <PolicyListSkeleton />;
  if (policiesQuery.isError) return <PolicyListError onRetry={() => policiesQuery.refetch()} />;

  return (
    <>
      {policiesQuery.isFetching && <RefreshingIndicator />}
      <PolicyTable policies={policiesQuery.data.items} />
    </>
  );
}

isPending means there is no data yet.

isFetching means a request is currently happening.

Those are not the same UX. If you show a full-page skeleton every time isFetching is true, your app will blink constantly. Keep the old data visible. Show a small refreshing indicator if the user needs to know.

This is one of the places where React apps start feeling calm.

Pagination Without Flicker

Pagination is where naive data fetching becomes obvious.

const policiesQuery = useQuery({
  queryKey: ['policies', page],
  queryFn: () => fetchPolicies({ page }),
});

Technically correct. Bad experience.

Every page is a different query key, so moving from page 1 to page 2 can bounce the UI back into a pending state. For tables, that feels like the screen is being rebuilt under the user's hands.

Use placeholderData: keepPreviousData:

import { keepPreviousData, useQuery } from '@tanstack/react-query';

export function PolicyListPage() {
  const [page, setPage] = useState(1);
  const filters = usePolicyListFilters();

  const policiesQuery = useQuery({
    ...policiesQueryOptions({ ...filters, page }),
    placeholderData: keepPreviousData,
  });

  if (policiesQuery.isPending) return <PolicyListSkeleton />;
  if (policiesQuery.isError) return <PolicyListError onRetry={() => policiesQuery.refetch()} />;

  return (
    <>
      <PolicyTable
        policies={policiesQuery.data.items}
        faded={policiesQuery.isPlaceholderData}
      />
      <Pagination
        page={page}
        hasNextPage={policiesQuery.data.hasNextPage}
        disabled={policiesQuery.isPlaceholderData}
        onPageChange={setPage}
      />
    </>
  );
}

Now the previous page stays visible while the next page loads. When the new data arrives, it swaps in. The UI doesn't fall through loading states just because the query key changed.

Small detail. Huge difference.

Dependent Queries

Some data needs another piece of data first.

The policy detail page loads the policy. Then it may load documents for the policy's customer account. You can't fetch those documents until you know the account id.

export function PolicyDetailPage() {
  const { policyId } = Route.useParams();

  const policyQuery = useQuery(policyDetailQueryOptions(policyId));

  const documentsQuery = useQuery({
    ...customerDocumentsQueryOptions(policyQuery.data?.customerAccountId ?? ''),
    enabled: Boolean(policyQuery.data?.customerAccountId),
  });

  // ...
}

The enabled flag is the important part. It says: this query exists, but it should not run until its input exists.

Don't put conditional hooks around this:

if (policyQuery.data) {
  const documentsQuery = useQuery(...);
}

React hooks don't work that way. Keep the hook unconditional. Control execution with enabled.

Prefetch at the Route Boundary

TanStack Router and TanStack Query fit together cleanly because route loaders can ensure query data before the page renders.

// src/pages/policy-detail/policy-detail.route.ts
export const policyDetailRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/policies/$policyId',
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(policyDetailQueryOptions(params.policyId)),
  component: PolicyDetailPage,
});

Then inside the page:

export function PolicyDetailPage() {
  const { policyId } = Route.useParams();
  const policyQuery = useQuery(policyDetailQueryOptions(policyId));

  return <PolicyDetailView policy={policyQuery.data} />;
}

The page still uses useQuery. That is good. The loader warms the cache; the component subscribes to it. You get route-level loading behavior without inventing a second data path.

For list-to-detail navigation, prefetch on intent:

function PolicyRow({ policy }: { policy: Policy }) {
  const queryClient = useQueryClient();

  return (
    <Link
      to="/policies/$policyId"
      params={{ policyId: policy.id }}
      onMouseEnter={() => {
        queryClient.prefetchQuery(policyDetailQueryOptions(policy.id));
      }}
    >
      {policy.policyNumber}
    </Link>
  );
}

Hover is not the only signal. Focus works for keyboard users. Intersection works for visible rows. The point is the same: fetch before the click when intent is clear enough.

Mutations Should Invalidate Narrowly

Mutations deserve their own full article later, but invalidation belongs here.

After editing a policy status:

export function useEditPolicyStatus() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updatePolicyStatus,
    onSuccess: (updatedPolicy) => {
      queryClient.setQueryData(
        policyKeys.detail(updatedPolicy.id),
        updatedPolicy,
      );

      queryClient.invalidateQueries({ queryKey: policyKeys.lists() });
    },
  });
}

Two things happen:

1. The detail cache gets the exact updated policy immediately.
2. Policy lists are invalidated because that status might affect filters, counts, and visible rows.

I prefer this over invalidating everything:

queryClient.invalidateQueries();

That is the data-fetching equivalent of turning the lights off and on again. Sometimes useful during development. Rarely the right production behavior.

Be specific. Your users can feel the difference.

Don't Mirror Query Data Into Local State

This is the smell I look for in reviews:

const policiesQuery = useQuery(policiesQueryOptions(filters));
const [policies, setPolicies] = useState<Policy[]>([]);

useEffect(() => {
  if (policiesQuery.data) {
    setPolicies(policiesQuery.data.items);
  }
}, [policiesQuery.data]);

Now there are two sources of truth. Query cache and local state. They will drift.

Usually the fix is simple:

const policies = policiesQuery.data?.items ?? [];

If you need derived data, derive it:

const activePolicies = useMemo(
  () => policiesQuery.data?.items.filter((policy) => policy.status === 'active') ?? [],
  [policiesQuery.data?.items],
);

If you need editable draft state, make that explicit:

const policyQuery = useQuery(policyDetailQueryOptions(policyId));
const form = useForm({
  defaultValues: policyQuery.data,
});

Server data can seed a draft. Once it becomes a draft, it is client state. Name the transition. Don't hide it in a useEffect.

The Review Checklist

When I review TanStack Query code, I ask:

• Does every query key include every variable used by the query function?
• Are keys created through a factory instead of hand-written arrays everywhere?
• Does each query have a deliberate staleTime?
• Is pagination using placeholderData when flicker would hurt?
• Are dependent queries controlled with enabled?
• Are route loaders using the same query options as components?
• Do mutations invalidate the narrowest useful key?
• Is query data being mirrored into local state unnecessarily?
• Does the UI distinguish first load from background refetch?

That checklist catches most of the data bugs I see in React applications.

What Comes Next

TanStack Query is the server-state layer. Once that layer is stable, routing becomes much easier to reason about: routes can preload the same query options, search params can drive query keys, and navigation can become type-safe instead of stringly typed.

Article #6: routing with TanStack Router — route trees, typed params, search validation, loaders, navigation, and how Router and Query should meet without turning every page into glue code.

The haunted policy list eventually became boring. Not because we added more spinners. Because the data model became explicit. Query keys had hierarchy. Freshness was intentional. Mutations invalidated the right caches. Pagination stopped flickering. Route loaders warmed the detail page before the user landed there.

That is what I want from data fetching in React.

Not cleverness. Calm.

If your React app has started to feel like the UI is arguing with the network, reach out. The fix is often not another loading state. It is giving server state one clear owner.

The first serious error-handling conversation on the insurance CRM happened after a demo.

We had built the policy detail page. It fetched the policy, loaded the customer, showed coverage sections, rendered a timeline, and pulled a list of recent changes. The happy path looked good. Fast enough. Clean enough. The kind of screen that makes a product manager relax for about five minutes.

Then the staging API returned a 500 for the timeline.

The whole page disappeared.

Not the timeline. Not the lower section. The entire policy detail page. A blank error screen replaced the policy number, the customer information, the coverage details, everything the agent actually needed to keep working.

The backend bug was real. But the frontend decision was worse: we had treated one failed widget as if the whole route was unusable.

I've watched this happen in multiple React apps. Error handling gets added late, after the components are built and the data flow already exists. Someone wraps the app in an Error Boundary, adds a few isError checks, maybe logs to Sentry, and calls it done.

It is not done.

Error handling is not just catching failures. It is deciding the blast radius of a failure.

A good error boundary is not a wall around your app. It is a circuit breaker around the smallest thing that can safely fail.

This article continues the React Playbook foundation. We already covered the stack, TypeScript patterns, and code structure. Now we need to talk about what happens when the happy path breaks: React Error Boundaries, TanStack Query error states, TanStack Router route errors, mutation failures, and the messages users actually deserve.

First, Separate Error Types

Most frontend error handling gets messy because teams put every failure in the same mental bucket.

They are not the same.

In a React app, I separate five categories:

1. Render errors — a component throws while rendering.
2. Route loading errors — a route cannot load the data required to show the page.
3. Query errors — a specific async resource failed.
4. Mutation errors — a user action failed.
5. Validation errors — user input is invalid before the request should happen.

Each one needs a different UX.

A render error is usually unexpected. You need containment, logging, and a recovery path.

A route loading error might mean the page cannot exist. If /policies/$policyId cannot load the policy at all, the page cannot show much.

A query error might only affect part of the screen. If recent activity fails, the user can still read the policy.

A mutation error happens after intent. The user clicked Save, Submit, Assign, Delete. The UI needs to explain what happened and preserve their work.

A validation error is not exceptional at all. It is part of the form flow.

When you model these separately, the code gets simpler. More importantly, the product gets calmer.

App-Level Error Boundary

React Error Boundaries catch errors thrown during rendering, lifecycle methods, and constructors of child components. They do not catch async errors from promises by default. TanStack Query and Router have their own integration points, which we'll get to.

For the app shell, you still want a top-level boundary:

// src/app/AppErrorBoundary.tsx
import { ErrorBoundary } from 'react-error-boundary';

interface AppErrorFallbackProps {
  error: Error;
  resetErrorBoundary: () => void;
}

function AppErrorFallback({ error, resetErrorBoundary }: AppErrorFallbackProps) {
  return (
    <main className="mx-auto flex min-h-screen max-w-xl flex-col justify-center p-6">
      <h1 className="text-2xl font-semibold">Something went wrong</h1>
      <p className="mt-3 text-muted-foreground">
        The application hit an unexpected error. You can try again, or refresh the page if the
        problem continues.
      </p>
      <pre className="mt-4 rounded-md bg-muted p-3 text-sm">{error.message}</pre>
      <button className="mt-6" onClick={resetErrorBoundary}>
        Try again
      </button>
    </main>
  );
}

export function AppErrorBoundary({ children }: { children: React.ReactNode }) {
  return (
    <ErrorBoundary
      FallbackComponent={AppErrorFallback}
      onError={(error, info) => {
        reportError(error, { componentStack: info.componentStack });
      }}
    >
      {children}
    </ErrorBoundary>
  );
}

Then wire it at the application edge:

// src/app/providers.tsx
import { QueryClientProvider } from '@tanstack/react-query';
import { AppErrorBoundary } from './AppErrorBoundary';
import { queryClient } from './query-client';

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <AppErrorBoundary>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </AppErrorBoundary>
  );
}

This is the last line of defense. It should almost never be the boundary your users see during normal failures.

If a single chart crashes, don't replace the entire app. If a sidebar widget crashes, don't hide the working page. Put smaller boundaries around risky areas.

Section-Level Boundaries

The policy detail page had several independent sections:

• policy header
• coverage summary
• beneficiaries
• recent activity timeline
• document attachments

The timeline was useful, but not essential. A timeline failure should not kill the route.

So give it a local boundary:

// src/widgets/recent-policy-activity/RecentPolicyActivityBoundary.tsx
import { ErrorBoundary } from 'react-error-boundary';
import { RecentPolicyActivity } from './RecentPolicyActivity';

function RecentPolicyActivityFallback() {
  return (
    <section className="rounded-md border p-4">
      <h2 className="font-medium">Recent activity</h2>
      <p className="mt-2 text-sm text-muted-foreground">
        Activity could not be loaded right now. The policy details are still available.
      </p>
    </section>
  );
}

export function RecentPolicyActivityBoundary({ policyId }: { policyId: string }) {
  return (
    <ErrorBoundary FallbackComponent={RecentPolicyActivityFallback}>
      <RecentPolicyActivity policyId={policyId} />
    </ErrorBoundary>
  );
}

The key sentence in the fallback is not "An error occurred." The key sentence is: the policy details are still available.

Users need to know scope. What broke? What still works? What can they do next?

TanStack Query: Local Error States First

TanStack Query gives you the query state directly:

const policyQuery = useQuery(policyDetailQueryOptions(policyId));

if (policyQuery.isPending) return <PolicyDetailSkeleton />;
if (policyQuery.isError) return <PolicyDetailError error={policyQuery.error} />;

return <PolicyDetailView policy={policyQuery.data} />;

This is the right pattern when the query owns the whole component. The component has one main job: load policy detail and render it. If that query fails, the component cannot do its job.

Make the error component specific:

// src/entities/policy/ui/PolicyDetailError.tsx
interface PolicyDetailErrorProps {
  error: Error;
  onRetry: () => void;
}

export function PolicyDetailError({ error, onRetry }: PolicyDetailErrorProps) {
  return (
    <div className="rounded-md border border-destructive/30 p-4">
      <h2 className="font-medium">Policy could not be loaded</h2>
      <p className="mt-2 text-sm text-muted-foreground">
        The policy may have been removed, or the server may be temporarily unavailable.
      </p>
      <p className="mt-2 text-xs text-muted-foreground">{error.message}</p>
      <button className="mt-4" onClick={onRetry}>
        Retry
      </button>
    </div>
  );
}

Then pass the retry:

if (policyQuery.isError) {
  return <PolicyDetailError error={policyQuery.error} onRetry={() => policyQuery.refetch()} />;
}

That refetch() matters. A dead error state with no recovery action forces the user to refresh the browser. That is not error handling. That is surrender.

Configure Query Defaults Deliberately

In article #1, we started with:

// src/app/query-client.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,
      retry: 1,
    },
  },
});

retry: 1 is not random. The TanStack Query default is three retries with exponential backoff. For some apps, that is fine. For internal CRM workflows, I usually prefer one retry.

Why?

Because three retries can make an error feel like a frozen screen. The user clicked a policy. The API is failing. The UI waits, retries, waits, retries, waits again, and only then shows an error. Technically resilient. Product-wise frustrating.

But not every query deserves the same retry behavior.

export function policyDetailQueryOptions(policyId: string) {
  return queryOptions({
    queryKey: policyKeys.detail(policyId),
    queryFn: () => fetchPolicyById(policyId),
    retry: (failureCount, error) => {
      if (isNotFoundError(error)) return false;
      return failureCount < 1;
    },
  });
}

Don't retry 404s. The policy isn't going to appear after a second attempt. Do retry one transient network failure. That is a reasonable default.

This is where typed API errors help.

Typed API Errors

In article #2, we talked about typing API responses at the boundary. Do the same for errors.

// src/shared/api/api-error.ts
export class ApiError extends Error {
  constructor(
    message: string,
    public readonly status: number,
    public readonly code?: string,
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

export function isApiError(error: unknown): error is ApiError {
  return error instanceof ApiError;
}

export function isNotFoundError(error: unknown) {
  return isApiError(error) && error.status === 404;
}

Use it in the HTTP client:

// src/shared/api/http-client.ts
import { ApiError } from './api-error';

export async function getJson<T>(url: string): Promise<T> {
  const response = await fetch(url);

  if (!response.ok) {
    const body = await response.json().catch(() => null);
    throw new ApiError(body?.message ?? `GET ${url} failed`, response.status, body?.code);
  }

  return response.json() as Promise<T>;
}

Now your UI can make product decisions:

function PolicyDetailError({ error, onRetry }: PolicyDetailErrorProps) {
  if (isNotFoundError(error)) {
    return (
      <EmptyState
        title="Policy not found"
        description="This policy may have been deleted or you may not have access to it."
      />
    );
  }

  return (
    <ErrorState
      title="Policy could not be loaded"
      description="The server did not return the policy. Try again in a moment."
      action={{ label: 'Retry', onClick: onRetry }}
    />
  );
}

A 404 and a 500 should not have the same message. One is probably permanent. One may be temporary. The UI should reflect that.

Route-Level Errors with TanStack Router

Some data is required before a route can render.

For a policy detail page, the policy itself is required. Recent activity is not. Attachments are not. Recommendations are not.

TanStack Router lets you load required data at the route level:

// src/pages/policy-detail/policy-detail.route.ts
export const policyDetailRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/policies/$policyId',
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(policyDetailQueryOptions(params.policyId)),
  errorComponent: PolicyDetailRouteError,
  component: PolicyDetailPage,
});

Then the route error component owns route-level failures:

// src/pages/policy-detail/PolicyDetailRouteError.tsx
import { useRouter } from '@tanstack/react-router';
import { isNotFoundError } from '@/shared/api';

export function PolicyDetailRouteError({ error }: { error: unknown }) {
  const router = useRouter();

  if (isNotFoundError(error)) {
    return (
      <RouteErrorLayout
        title="Policy not found"
        description="The policy does not exist, was removed, or is not available to your account."
        action={{ label: 'Back to policies', to: '/policies' }}
      />
    );
  }

  return (
    <RouteErrorLayout
      title="Policy could not be opened"
      description="Something failed while loading this policy. You can retry without leaving the page."
      action={{ label: 'Retry', onClick: () => router.invalidate() }}
    />
  );
}

router.invalidate() is the route-level retry. It re-runs loaders and gives the route a chance to recover.

The important design choice is deciding what belongs in the loader. If every widget query goes into the loader, every widget failure becomes a route failure. That is exactly how we blanked the policy detail page in the demo.

My rule:

Load the minimum data required to make the route meaningful. Everything else should fail locally.

Mutation Errors Are Different

Query errors happen while reading.

Mutation errors happen after the user did something.

That difference matters. A failed mutation should preserve the user's input, explain what happened, and make retry obvious.

// src/features/edit-policy-status/ui/EditPolicyStatusForm.tsx
export function EditPolicyStatusForm({ policyId }: { policyId: string }) {
  const editStatus = useEditPolicyStatus();

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        editStatus.mutate({ policyId, status: 'active' });
      }}
    >
      {editStatus.isError && (
        <InlineError>
          Status could not be updated. Your change was not saved. Try again in a moment.
        </InlineError>
      )}

      <button disabled={editStatus.isPending}>
        {editStatus.isPending ? 'Saving...' : 'Save status'}
      </button>
    </form>
  );
}

Notice the wording: Your change was not saved.

Users need to know whether the action happened. Ambiguous mutation errors are dangerous. Did the payment submit? Did the policy update? Did the customer receive the email? If the system cannot guarantee success, say so clearly.

For destructive actions, be even more explicit:

<InlineError>
  The document was not deleted. The server rejected the request, so it is still attached to the
  policy.
</InlineError>

That kind of sentence sounds small. In operational software, it matters.

Optimistic Updates Need Rollback

TanStack Query makes optimistic updates straightforward, but optimistic error handling has to be designed.

// src/features/edit-policy-status/api/edit-policy-status.mutation.ts
export function useEditPolicyStatus() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updatePolicyStatus,
    onMutate: async (variables) => {
      await queryClient.cancelQueries({ queryKey: policyKeys.detail(variables.policyId) });

      const previousPolicy = queryClient.getQueryData<PolicyDetail>(
        policyKeys.detail(variables.policyId),
      );

      queryClient.setQueryData<PolicyDetail>(policyKeys.detail(variables.policyId), (policy) =>
        policy ? { ...policy, status: variables.status } : policy,
      );

      return { previousPolicy };
    },
    onError: (_error, variables, context) => {
      queryClient.setQueryData(policyKeys.detail(variables.policyId), context?.previousPolicy);
    },
    onSettled: (_data, _error, variables) => {
      queryClient.invalidateQueries({ queryKey: policyKeys.detail(variables.policyId) });
    },
  });
}

Optimistic UI is a promise: "we'll show the result now and clean it up if the server disagrees."

If you don't roll back, it becomes a lie.

Honestly, I use optimistic updates less often than people expect. They are excellent for low-risk interactions: toggles, lightweight status changes, local ordering. For payments, legal records, irreversible actions, or anything with compliance implications, I prefer boring pending states and clear confirmation.

Fast is good. Correct is better.

Validation Errors Are Not Exceptions

Form validation errors should not go through Error Boundaries, route error components, or global toasts.

They belong next to the field or section that needs correction.

// src/features/create-policy/ui/CreatePolicyForm.tsx
<form.Field
  name="holderName"
  validators={{
    onBlur: ({ value }) => {
      if (!value.trim()) return 'Policy holder name is required';
      return undefined;
    },
  }}
>
  {(field) => (
    <TextField
      label="Policy holder"
      value={field.state.value}
      onBlur={field.handleBlur}
      onChange={(event) => field.handleChange(event.target.value)}
      error={field.state.meta.errors[0]}
    />
  )}
</form.Field>

A validation message is not an apology. It is guidance.

Bad:

Invalid value.

Better:

Policy holder name is required.

Better still, when the rule is domain-specific:

Coverage start date must be after the policy approval date.

The closer the error is to the user's mental model, the less support burden you create.

Global Toasts Are Not an Error Strategy

I have a strong bias here: global error toasts are overused.

They are fine for background actions:

Report export failed. Try again later.

They are not fine as the only feedback for a failed form submit, failed route load, or failed section query.

Toasts disappear. They are hard to reread. They often don't say what changed. If the user needs the information to continue, put it in the interface where the failure happened.

Use toasts for secondary notifications. Use inline states for primary failures.

Logging Without Leaking

You still need error reporting.

But don't send everything everywhere. A useful report has context:

// src/shared/lib/report-error.ts
interface ErrorContext {
  route?: string;
  policyId?: string;
  componentStack?: string;
  action?: string;
}

export function reportError(error: unknown, context: ErrorContext = {}) {
  if (import.meta.env.DEV) {
    console.error(error, context);
    return;
  }

  // Send to your reporting tool here.
  // Include context, but avoid sensitive policy/customer data.
}

For a CRM, this matters. Policy numbers, customer names, payment details, medical information, internal notes — these should not casually land in logs because a component threw.

Log identifiers when needed. Avoid payloads unless you have a reason and a retention policy.

A Practical Error-Handling Checklist

When I review a React screen, I ask these questions:

• What data is required for the route to be meaningful?
• What data can fail locally without killing the page?
• Does every failed query have a retry path?
• Does every failed mutation preserve user input?
• Does the user know whether their action was saved?
• Are 404, 403, 409, and 500 treated differently where it matters?
• Are validation errors close to the fields?
• Are unexpected errors logged with useful context and without sensitive data?

This is not bureaucracy. This is how you keep production software calm.

What Comes Next

The first four articles now cover the base layer of a serious React application:

• Article #1: the stack
• Article #2: TypeScript patterns
• Article #3: code structure
• Article #4: this error-handling model

Article #5: data fetching with TanStack Query — query keys, cache shape, prefetching, invalidation, stale time, pagination, and the boring details that decide whether a React app feels reliable or twitchy.

After that staging demo, we changed the policy detail page. The policy itself stayed route-level. The timeline moved into a local query with its own fallback. Attachments got a retry button. Mutations kept user input visible after failure. The app did not become immune to backend problems. No frontend can do that.

But failures became smaller.

That is the whole point. Not hiding errors. Not pretending the system is fine. Making sure one broken piece does not take the rest of the work down with it.

If you're designing error handling for a React app and every failure currently becomes either a toast or a blank screen, reach out. There is usually a calmer architecture hiding one boundary lower.

At the insurance company, our React app started with a structure I still like for small projects.

src/
  api/
  components/
  hooks/
  layouts/
  pages/
  types/
  router.ts
  main.tsx

For the first few months, it worked. A policy list page lived in pages/. Shared buttons lived in components/. Fetch functions lived in api/. Everyone understood where things went.

Then the policy builder arrived.

It was not a page anymore. It was a product inside the product: dynamic fields, conditional sections, autosave, permissions, validation, optimistic updates, draft recovery, and analytics. Suddenly one change touched pages/, api/, types/, hooks/, components/, and a couple of files nobody remembered creating.

I've seen this pattern across multiple teams. A flat structure doesn't fail all at once. It fails quietly. First you add one more shared hook. Then one more domain type. Then a generic component that is not generic at all, just shared too early. Six months later the folders are still clean, but every feature is smeared across the project.

That is usually the moment people reach for Feature-Sliced Design.

Honestly, I think that instinct is right. FSD gives React projects a language for scale: layers, slices, public APIs, dependency direction. But if you apply it mechanically, it creates a different problem. The code becomes "architecturally correct" and painful to work with.

This article is the version I actually use in production React apps. Not pure FSD. Not flat folders forever. A practical structure for TanStack Query, TanStack Router, TanStack Form, and the kind of domain logic that appears in real applications.

Architecture should make the next change easier to locate, not just easier to categorize.

Start Flat, Then Move When Pain Appears

I don't start every React app with full FSD.

For a new Vite + TanStack project, this is still a good beginning:

src/
  api/
    policies.ts
    query-keys.ts
  components/
    Button.tsx
    DataList.tsx
  layouts/
    RootLayout.tsx
  pages/
    PolicyListPage.tsx
    PolicyDetailPage.tsx
  types/
    policy.ts
  router.ts
  main.tsx

This structure is boring. Boring is good at the start.

The mistake is keeping it after the app stops being boring. You don't need FSD because the project has ten files. You need it when features become independent units of change.

The signal is not folder count. The signal is change pattern.

If every policy-related change touches five top-level folders, the structure is telling you something. If onboarding a developer requires explaining "policy things are in several places, you'll get used to it," the structure is telling you something. If a file is in shared/ because two components use it but both components belong to the same feature, the structure is telling you something.

At that point, I move to a sliced structure.

The Structure

The shape I use most often:

src/
  app/
    router.ts
    providers.tsx
    query-client.ts
  pages/
    policy-list/
      PolicyListPage.tsx
      route.ts
    policy-detail/
      PolicyDetailPage.tsx
      route.ts
  widgets/
    policy-search-panel/
    policy-summary-card/
  features/
    create-policy/
    edit-policy-status/
    assign-policy-owner/
  entities/
    policy/
      api/
      model/
      ui/
      lib/
      index.ts
    customer/
      api/
      model/
      ui/
      index.ts
  shared/
    api/
    config/
    lib/
    ui/

The names come from FSD, but the goal is not to worship the names. The goal is to separate code by responsibility and change frequency.

app/ is application wiring. Providers, router creation, query client configuration, global error boundaries. It should know how the app starts. It should not know how policy validation works.

pages/ are route-level screens. They compose widgets, features, and entities. They should be thin. If a page file becomes a business logic container, something probably belongs lower.

widgets/ are larger UI blocks made from several domain pieces. A search panel, a dashboard section, a header with account controls.

features/ are user actions. Create policy. Update status. Assign owner. Submit payment method.

entities/ are domain concepts. Policy. Customer. Beneficiary. Claim. This is where domain types, query keys, API functions, selectors, and reusable entity UI usually live.

shared/ is for things that are truly domain-agnostic: buttons, date formatting, HTTP client, environment config, tiny utilities.

The import direction matters:

app -> pages -> widgets -> features -> entities -> shared

Lower layers don't import higher layers. entities/policy should not import from features/create-policy. shared/ui/Button should not know a policy exists.

That one rule prevents a lot of architectural rot.

Where TanStack Query Goes

The most common question in this stack: where do query hooks live?

My default: query keys and fetch functions live in the entity. Feature-specific mutations live in the feature if they represent a user action.

src/
  entities/
    policy/
      api/
        policy.api.ts
        policy.queries.ts
      model/
        policy.types.ts
      index.ts
  features/
    edit-policy-status/
      api/
        edit-policy-status.mutation.ts
      ui/
        EditPolicyStatusButton.tsx
      index.ts

The entity owns the stable data contract:

// src/entities/policy/api/policy.queries.ts
import { queryOptions } from '@tanstack/react-query';
import { fetchPolicyById, fetchPolicies } from './policy.api';

export const policyKeys = {
  all: ['policies'] as const,
  lists: () => [...policyKeys.all, 'list'] as const,
  list: (filters: PolicyListFilters) => [...policyKeys.lists(), filters] as const,
  details: () => [...policyKeys.all, 'detail'] as const,
  detail: (policyId: string) => [...policyKeys.details(), policyId] as const,
};

export function policiesQueryOptions(filters: PolicyListFilters) {
  return queryOptions({
    queryKey: policyKeys.list(filters),
    queryFn: () => fetchPolicies(filters),
  });
}

export function policyDetailQueryOptions(policyId: string) {
  return queryOptions({
    queryKey: policyKeys.detail(policyId),
    queryFn: () => fetchPolicyById(policyId),
  });
}

The feature owns the action:

// src/features/edit-policy-status/api/edit-policy-status.mutation.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { policyKeys } from '@/entities/policy';
import { updatePolicyStatus } from './edit-policy-status.api';

export function useEditPolicyStatus() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: updatePolicyStatus,
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries({ queryKey: policyKeys.detail(variables.policyId) });
      queryClient.invalidateQueries({ queryKey: policyKeys.lists() });
    },
  });
}

This keeps the split honest. Reading policy data is part of the policy entity. Editing a status is a user action, so it belongs to a feature.

Could you put all mutations inside entities/policy? Sometimes, yes. For simple CRUD apps it works. But once mutations include permissions, analytics, form state, toasts, optimistic updates, or workflow-specific behavior, I prefer feature ownership. The code changes with the feature, so it should live with the feature.

Where TanStack Router Goes

TanStack Router adds an interesting pressure: route definitions are code, and code wants to be near the page it renders.

For small apps, one src/router.ts is fine. For larger apps, I split route pieces by page and compose them in app/router.ts.

src/
  app/
    router.ts
  pages/
    policy-list/
      PolicyListPage.tsx
      policy-list.route.ts
    policy-detail/
      PolicyDetailPage.tsx
      policy-detail.route.ts

// src/pages/policy-detail/policy-detail.route.ts
import { createRoute } from '@tanstack/react-router';
import { rootRoute } from '@/app/root-route';
import { policyDetailQueryOptions } from '@/entities/policy';
import { PolicyDetailPage } from './PolicyDetailPage';

export const policyDetailRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/policies/$policyId',
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(policyDetailQueryOptions(params.policyId)),
  component: PolicyDetailPage,
});

The page route can import from entities because pages sit above entities. The entity must never import the route.

This also makes preloading natural. The route knows it needs a policy detail. The entity knows how to describe that query. TanStack Router and TanStack Query meet at the page boundary instead of leaking through the whole application.

Where TanStack Form Goes

Forms are where clean architecture usually goes to suffer.

A form is not just UI. It has schema, default values, validation, submission, dirty state, field components, and often domain-specific rules. If you split those across shared/forms/, entities/, features/, and pages/ too early, every form change becomes a small hunt.

My rule:

Put the form where the user action lives. Extract only the parts that are genuinely reused by another action.

For creating a policy:

src/
  features/
    create-policy/
      model/
        create-policy.schema.ts
        create-policy.types.ts
      api/
        create-policy.mutation.ts
      ui/
        CreatePolicyForm.tsx
        CoverageSection.tsx
        BeneficiariesSection.tsx
      index.ts

The feature owns the form because the form exists to perform the feature.

If CoverageSection later appears in three different policy workflows, then move it. Not before. Premature sharing is one of the fastest ways to make React code harder to change.

This is especially important with TanStack Form because field-level logic tends to be close to business rules:

// src/features/create-policy/ui/CreatePolicyForm.tsx
import { useForm } from '@tanstack/react-form';
import { createPolicySchema } from '../model/create-policy.schema';
import { useCreatePolicy } from '../api/create-policy.mutation';

export function CreatePolicyForm() {
  const createPolicy = useCreatePolicy();

  const form = useForm({
    defaultValues: {
      holderName: '',
      coverageType: 'standard',
      beneficiaries: [],
    },
    validators: {
      onSubmit: createPolicySchema,
    },
    onSubmit: ({ value }) => createPolicy.mutate(value),
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        form.handleSubmit();
      }}
    >
      {/* fields */}
    </form>
  );
}

The schema, mutation, and UI are close because they change together. That is not messy. That is locality.

What Belongs in Shared

shared/ is the most abused folder in React architecture.

If a file feels "not specific enough," people put it in shared. Then shared becomes the new junk drawer: domain helpers, half-generic hooks, components with policy-specific props, validation rules from one workflow, and API helpers that know too much.

I use a stricter test.

A file belongs in shared/ only if it can be moved to a different product in the same company and still make sense.

Good candidates:

shared/
  api/
    http-client.ts
  config/
    env.ts
  lib/
    format-date.ts
    assert-never.ts
  ui/
    Button.tsx
    Dialog.tsx
    TextField.tsx

Bad candidates:

shared/
  hooks/
    usePolicyValidation.ts
  lib/
    calculateCoveragePremium.ts
  ui/
    PolicyStatusBadge.tsx

Those are not shared. They are policy code. Put them in entities/policy or in the feature that owns the workflow.

This one discipline keeps FSD useful. When shared stays small, the rest of the architecture stays readable.

Public APIs: The Boring Part That Matters

Every slice should expose a public API through index.ts.

src/entities/policy/index.ts

export type { Policy, PolicyDetail, PolicyStatus } from './model/policy.types';
export { policyKeys, policyDetailQueryOptions, policiesQueryOptions } from './api/policy.queries';
export { PolicyStatusBadge } from './ui/PolicyStatusBadge';

Then other layers import from the slice root:

import { PolicyStatusBadge, policyDetailQueryOptions } from '@/entities/policy';

Not from internal paths:

import { policyDetailQueryOptions } from '@/entities/policy/api/policy.queries';

The public API gives you a boundary. You can reorganize internals without updating imports across the whole app. It also forces a small moment of intent: is this thing actually meant to be used outside the slice?

That question catches more design mistakes than people expect.

The Rule I Break on Purpose

Pure FSD can become too granular for real feature work. I break one rule deliberately: I colocate deeply related feature files even when they could be classified into separate layers.

If CreatePolicyForm, createPolicySchema, createPolicyMutation, and CoverageSection always change together, I keep them in features/create-policy.

I don't move CoverageSection to widgets/ because it looks like a block.

I don't move createPolicySchema to entities/policy because it mentions policy fields.

I don't move a tiny helper to shared/lib because two files in the same feature use it.

This is not laziness. It is a design choice.

I've been in the room where a team spent twenty minutes arguing whether a file was a feature, an entity, or a widget. Different company, different stack, same argument. At some point, the question stops being architectural and starts being clerical.

When that happens, I ask a simpler question: what changes with this file?

If the answer is "this feature," it stays in the feature.

A Migration Path That Doesn't Hurt

You don't need to restructure the entire app in one PR.

Start with one domain that already hurts. In the insurance CRM, that would have been policies.

Before:

src/
  api/policies.ts
  components/PolicyStatusBadge.tsx
  hooks/usePolicyFilters.ts
  pages/PolicyListPage.tsx
  pages/PolicyDetailPage.tsx
  types/policy.ts

After:

src/
  entities/
    policy/
      api/
        policy.api.ts
        policy.queries.ts
      model/
        policy.types.ts
      ui/
        PolicyStatusBadge.tsx
      index.ts
  pages/
    policy-list/
      PolicyListPage.tsx
    policy-detail/
      PolicyDetailPage.tsx

Then move the next workflow into features/ when you touch it for real work.

Don't create empty folders for future architecture. Empty architecture is theater. Let structure follow actual code.

How I Know the Structure Is Working

Good structure has practical symptoms.

A new feature starts in one folder. A domain type is easy to find. Query invalidation is predictable. Shared stays boring. A page reads like composition instead of orchestration.

More importantly, changes have shape.

When a status-editing bug appears, you know to open features/edit-policy-status. When a policy response changes, you know to open entities/policy. When route preloading fails, you know to look at the page route.

That is the payoff. Not prettier folders. Faster orientation.

What Comes Next

The first three articles now give us the foundation:

• Article #1: the starting stack — Vite, TanStack Query, Router, Form, and the minimal setup
• Article #2: TypeScript patterns — typed API boundaries, query keys, route params, async state
• Article #3: this structure — how those pieces live together once the app grows

Article #4: error handling — Error Boundaries, TanStack Query error states, route-level failures, and what to show users when the happy path breaks.

That policy builder eventually became one of the busiest parts of the insurance CRM. The structure was not perfect. No structure is. But after we moved policy code into a domain slice and kept workflow-specific logic inside features, the app became easier to reason about.

Not because FSD solved architecture for us. Because it gave us enough structure to stop guessing, and enough flexibility to keep related code close.

That's the version I trust: architecture as a working agreement, not a folder ceremony.

If you're trying to move a React codebase from flat folders into something more deliberate, feel free to reach out. The hard part is rarely naming the folders. The hard part is deciding what should change together.

Six weeks into the insurance CRM project, we had a production incident. The backend team renamed a field — policy_number became policyNumber — as part of a snake_case-to-camelCase API migration. The migration happened on a Friday. By Monday morning, the policy list was blank for every user.

The bug took four minutes to find. The cause took longer to accept: we had typed the API response as any. Not carelessly — the original developer had written a comment: "TODO: add proper types." The TODO was six months old.

Honest answer: I've seen this exact scenario more times than I want to count. TypeScript installed, TypeScript ignored at the boundaries. any at the API layer, loose props in the middle, and full type safety only in the parts that didn't need it — utility functions, helpers, things that already worked.

This article is not a TypeScript tutorial. If you need to understand generics from first principles, there are better resources for that. What I want to cover are the specific patterns that prevent real production bugs in React + TanStack apps. The ones I reach for on every project now, not as best practices, but because I've seen what happens without them.

Pattern 1: The Typed API Layer

The most important rule: type your API responses at the boundary, once.

Not in the component. Not in the hook. At the fetch function that talks to the API. Everything downstream inherits the types automatically.

// src/api/policies.ts
import type { Policy, PolicyDetail } from '../types/policy';

export async function fetchPolicies(): Promise<Policy[]> {
  const res = await fetch('/api/policies');
  if (!res.ok) throw new Error(`GET /api/policies failed: ${res.status}`);
  return res.json() as Promise<Policy[]>;
}

export async function fetchPolicyById(policyId: string): Promise<PolicyDetail> {
  const res = await fetch(`/api/policies/${policyId}`);
  if (!res.ok) throw new Error(`GET /api/policies/${policyId} failed: ${res.status}`);
  return res.json() as Promise<PolicyDetail>;
}

// src/types/policy.ts
export interface Policy {
  id: string;
  policyNumber: string;
  holderName: string;
  status: 'active' | 'expired' | 'pending';
  effectiveDate: string;
}

export interface PolicyDetail extends Policy {
  coverageType: string;
  premiumAmount: number;
  beneficiaries: Beneficiary[];
}

export interface Beneficiary {
  id: string;
  name: string;
  relationship: string;
  percentage: number;
}

Now useQuery({ queryFn: fetchPolicies }) returns Policy[] — typed, autocompleted, checked at every usage. When the backend changes policyNumber to something else, TypeScript tells you before production.

The as Promise<Policy[]> cast on res.json() is intentional. res.json() returns Promise<unknown> in recent TypeScript. We're making an explicit contract: this fetch function guarantees this shape. If you want runtime validation as well, add Zod:

import { z } from 'zod';

const PolicySchema = z.object({
  id: z.string(),
  policyNumber: z.string(),
  holderName: z.string(),
  status: z.enum(['active', 'expired', 'pending']),
  effectiveDate: z.string(),
});

export async function fetchPolicies(): Promise<Policy[]> {
  const res = await fetch('/api/policies');
  if (!res.ok) throw new Error(`GET /api/policies failed: ${res.status}`);
  const raw = await res.json();
  return z.array(PolicySchema).parse(raw);
}

With Zod, a field rename or unexpected shape becomes a runtime error with a descriptive message, not a blank screen with no useful stack trace. Article #4 covers error handling strategies — for now, know this option exists.

Pattern 2: Query Key Factories

Query keys in TanStack Query are arrays. They look harmless until you have fifty queries and someone types ['policy', policyId] in one file and ['policies', id] in another. Invalidation stops working silently.

The fix is a query key factory — one object that owns all keys for a domain:

// src/api/query-keys.ts
export const policyKeys = {
  all: ['policies'] as const,
  lists: () => [...policyKeys.all, 'list'] as const,
  list: (filters: PolicyListFilters) => [...policyKeys.lists(), filters] as const,
  details: () => [...policyKeys.all, 'detail'] as const,
  detail: (id: string) => [...policyKeys.details(), id] as const,
};

Usage:

// In PolicyListPage
useQuery({
  queryKey: policyKeys.list({ status: 'active' }),
  queryFn: () => fetchPolicies({ status: 'active' }),
});

// In mutation after update
queryClient.invalidateQueries({ queryKey: policyKeys.lists() });

// In PolicyDetailPage
useQuery({
  queryKey: policyKeys.detail(policyId),
  queryFn: () => fetchPolicyById(policyId),
});

The as const assertions make the arrays readonly tuples instead of (string | PolicyListFilters)[], which means TypeScript knows the exact structure. When you call invalidateQueries({ queryKey: policyKeys.lists() }), it correctly invalidates all list queries regardless of their filter arguments, because the key hierarchy matches.

This is a pattern I keep coming back to. Centralizing keys also makes it trivial to audit which queries exist in an application — you read one file.

Pattern 3: Discriminated Unions for Async State

The classic approach to async state in React:

const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

This is three independent booleans representing one state machine. The problem: you can have loading: true and data: something at the same time. TypeScript can't tell you that's impossible. Your component has to handle combinations that shouldn't exist.

TanStack Query solves this with its own state machine, but when you need custom async state — or when you want to model UI states explicitly — discriminated unions are the right tool:

// src/types/async-state.ts
export type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'error'; error: Error }
  | { status: 'success'; data: T };

Usage in a component:

function PolicyDetail({ policyId }: { policyId: string }) {
  const query = useQuery({
    queryKey: policyKeys.detail(policyId),
    queryFn: () => fetchPolicyById(policyId),
  });

  if (query.isPending) return <PolicyDetailSkeleton />;
  if (query.isError) return <ErrorMessage error={query.error} />;

  // TypeScript now knows query.data is PolicyDetail — not PolicyDetail | undefined
  const policy = query.data;

  return (
    <div>
      <h1>{policy.policyNumber}</h1>
      <p>{policy.holderName}</p>
    </div>
  );
}

After the isError guard, TypeScript narrows query.data to the non-undefined type. This is TanStack Query's built-in discriminated union working correctly. The principle applies when you build your own async state machines: model them as discriminated unions from the start, and TypeScript narrows automatically when you check status.

TypeScript's type narrowing is only as good as your state model. If your state model allows impossible combinations, no amount of type annotations fixes that.

Pattern 4: Typed Route Params with TanStack Router

This is where TanStack Router pays for itself. In article #1, we set up the router with a Register declaration. Here's what that gives you:

// src/pages/PolicyDetailPage.tsx
import { useParams } from '@tanstack/react-router';

export function PolicyDetailPage() {
  // policyId is string — typed against the route definition
  // TypeScript error if this route doesn't have $policyId
  const { policyId } = useParams({ from: '/policies/$policyId' });

  // ...
}

Compare to React Router:

// React Router — manual cast, no safety
const { policyId } = useParams<{ policyId: string }>();

The React Router version compiles even if the route doesn't exist. The TanStack Router version fails to compile if the route doesn't have $policyId. That's the difference between type annotations and type inference.

Search params work the same way, but you need to define a validator on the route:

// src/router.ts
import { z } from 'zod';

const policyListSearchSchema = z.object({
  status: z.enum(['active', 'expired', 'pending']).optional(),
  page: z.number().int().positive().optional().default(1),
});

const policyListRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/policies',
  validateSearch: policyListSearchSchema,
  component: PolicyListPage,
});

// In PolicyListPage
const { status, page } = useSearch({ from: '/policies' });
// status: 'active' | 'expired' | 'pending' | undefined
// page: number (default 1)

Search params validated with Zod, typed at the component level, consistent across navigation. No URLSearchParams parsing. No manual type assertions. Navigating to /policies?status=invalid either throws at the router level or falls back to the default — you control the behavior.

Pattern 5: Generic Data Components

React components that render lists of things are everywhere. The naive approach writes a new component for every list. The slightly better approach passes items as any[]. The right approach uses generics:

// src/components/DataList.tsx
interface DataListProps<T> {
  items: T[];
  getKey: (item: T) => string;
  renderItem: (item: T) => React.ReactNode;
  emptyMessage?: string;
}

export function DataList<T>({
  items,
  getKey,
  renderItem,
  emptyMessage = 'No items found',
}: DataListProps<T>) {
  if (items.length === 0) {
    return <p className="text-muted-foreground">{emptyMessage}</p>;
  }

  return (
    <ul className="space-y-2">
      {items.map((item) => (
        <li key={getKey(item)}>{renderItem(item)}</li>
      ))}
    </ul>
  );
}

Usage:

<DataList
  items={policies}
  getKey={(p) => p.id}
  renderItem={(p) => <PolicyRow policy={p} />}
  emptyMessage="No policies match this filter"
/>

TypeScript infers T as Policy from the items prop. The getKey and renderItem functions are typed to Policy automatically. You can't pass a Beneficiary to renderItem by accident.

This pattern works for any container component: tables, grids, selects, autocompletes. Write it once, use it everywhere, get full type safety for free.

Pattern 6: Typed Context

React Context is commonly the place where types collapse to any or to T | undefined that requires a null check at every usage. A cleaner pattern:

// src/context/auth-context.tsx
interface AuthContextValue {
  userId: string;
  role: 'admin' | 'agent' | 'viewer';
  logout: () => void;
}

const AuthContext = React.createContext<AuthContextValue | null>(null);

export function useAuth(): AuthContextValue {
  const ctx = React.useContext(AuthContext);
  if (!ctx) throw new Error('useAuth must be used within AuthProvider');
  return ctx;
}

The context itself accepts null (before the provider mounts). The useAuth hook throws if used outside the provider and returns the non-null type. Every component that calls useAuth() gets AuthContextValue without optional chaining. The invariant is checked once, at the hook boundary.

This is not a new pattern. It's in the React docs. But I keep seeing codebases where context values are T | undefined and components are littered with auth?.userId ?? ''. The throw-in-the-hook approach pushes the validation to the right place and cleans up every callsite.

What to Carry Forward

These six patterns cover the majority of TypeScript friction I encounter in React codebases:

• Typed API layer — type once at the boundary, inherit everywhere
• Query key factories — centralize keys, prevent invalidation bugs
• Discriminated unions — model states correctly, let TypeScript narrow
• TanStack Router inference — route params typed against actual routes, not manual casts
• Generic components — one implementation, full type safety across all usages
• Typed context with throwing hooks — clean callsites, invariant checked once

None of these require advanced TypeScript knowledge. They require the discipline to type at boundaries instead of in the middle, and to model state as what it actually is rather than what's convenient.

Six months after that production incident, the insurance CRM had a typed API layer across every endpoint and Zod validation on the most critical ones. We had two more backend field renames during that time. Neither reached production. TypeScript caught both during development, before the PRs were even reviewed.

That's the whole point — not type coverage as a metric, but fewer incidents as an outcome.

If you're working through TypeScript patterns in a React codebase and hitting specific friction points — reach out. These problems are usually more mechanical than they appear.

I joined a project where everyone was writing code. Not just developers — project managers, analysts, even a designer who had never seen a terminal in his life. They would open VS Code, fire up Google's Gemini, and ask it to move a button, change a color, add border radius, tweak spacing. And the agent would do it. The code would work. And the codebase would get a little worse every time.

Because the agent had no context. It didn't know the project used a design system. It didn't know there were shared components for exactly these things. It didn't know that some files used CSS modules, others used inline styles, and a third group used something else entirely. So every AI-generated change was technically correct and architecturally wrong. The codebase turned into a patchwork of conflicting approaches.

I spent almost two weeks writing structured project documentation specifically for the agent. Architecture, component rules, naming conventions, styling approach, the whole picture. And then I ran my own test: I told the agent, "Find 20 components that have something to fix." That's it. A dead simple, almost primitive prompt. The agent — now armed with full project context — went through the codebase, found real issues (wrong styling approach, missing design tokens, inconsistent patterns), and fixed them on the spot. It was the moment I realized: the model was never the problem. The missing context was.

Context

Most teams treat AI coding agents like extremely smart autocomplete. The agent sees the open files, maybe a README, and a prompt like "implement this feature".

That's rarely enough.

In real projects, the missing context is huge:

• Why the product exists
• Who the users are
• Architectural constraints
• Coding standards
• Testing expectations
• Future migration plans

Humans fill these gaps from experience and project history. Agents don't.

While working on enterprise projects (including work done for large companies such as Procter & Gamble and MedMe), I noticed the same pattern: agents generate better code when the project explicitly describes itself.

The solution that emerged was surprisingly simple.

Create a dedicated documentation layer designed for AI agents.

Not a README. Not a wiki.

A structured project context directory.

Core Concept

The core idea is straightforward:

AI agents need explicit, structured context about the project.

Instead of relying on scattered documentation, the project exposes its knowledge in a predictable location.

Example:

/docs
  product.md
  architecture.md
  coding-standards.md
  testing-strategy.md
  code-review.md
  design-system.md
  roadmap.md
  third-party-services.md

An index file explains what each document contains and when an agent should read it.

Example:

docs/index.md

product.md
Short overview of the product: users, business goals, main workflows.

architecture.md
High-level architecture of the frontend and backend systems.

coding-standards.md
Project conventions and linting rules the agent must follow.

testing-strategy.md
What must be tested and how tests should be written.

Then the main instruction file references this folder.

Example:

AGENT.md

When working on this project you MUST read the docs folder.

Start with:
docs/index.md

Based on the task you may need to read:
- architecture.md
- coding-standards.md
- testing-strategy.md
- design-system.md

This approach turns documentation into something closer to a context API for agents.

Implementation Example

A simplified instruction file for an agent might look like this:

# AGENT.md

This repository contains a React + Next.js application.

Before implementing any feature:
1. Read docs/index.md
2. Identify which documents are relevant for the task
3. Follow project conventions strictly

Key constraints:

- Use TypeScript strict mode
- Follow design tokens defined in docs/design-system.md
- All components must have tests (see docs/testing-strategy.md)
- Follow code review rules defined in docs/code-review.md

Example of coding standards exposed to the agent:

# coding-standards.md

Component rules:

- Components must be colocated with tests
- Use function components only
- Avoid default exports

Folder structure:

components/
  Button/
    Button.tsx
    Button.test.tsx
    Button.styles.ts

Example of testing expectations:

# testing-strategy.md

All UI components must include:

- unit tests (Vitest)
- interaction tests
- accessibility checks where applicable

Example:

describe("Button", () => {
  it("renders label", () => {})
  it("triggers click handler", () => {})
})

Once this context exists, agents consistently generate code that is much closer to what a real team would accept.

Integrating Task Context via MCP

Documentation alone is useful, but it becomes much more powerful when combined with external context.

Using MCP integrations, an agent can retrieve additional project history:

• Jira tasks
• Git commits
• bug reports
• previous discussions

Example workflow:

1. Agent works on a component
2. It inspects commit history
3. Extracts issue IDs
4. Queries Jira via MCP
5. Reads bug descriptions

This allows the agent to understand things like:

• why a component was implemented in a specific way
• what bugs previously occurred
• which constraints must not be broken

Without this, agents tend to unknowingly reintroduce old bugs.

Where It Breaks in Enterprise

This approach works well, but it introduces new challenges.

Documentation drift

Docs become outdated quickly if they are not maintained.

Agents will follow outdated rules very confidently.

Over-documentation

Too many documents create the opposite problem: agents get lost in irrelevant context.

Keep documentation focused and scoped.

Missing architectural intent

If architecture documents only describe current implementation but not intent, agents will optimize locally and break long-term plans.

For example:

• migrating from Redux to TanStack Query
• replacing a design system
• upgrading React versions

Agents need to know about these plans.

Common Mistakes

Treating README as agent documentation

README files are written for humans. They are narrative and incomplete.

Agents work better with:

• short
• structured
• explicit documentation.

Documenting only code structure

Agents also need business context.

Example:

Users: pharmacists
Main workflow: reviewing prescriptions
Critical requirement: audit traceability

Without this, agents optimize code but miss product constraints.

Not documenting code review expectations

Agents can generate correct code that still fails review.

For example:

• missing tests
• wrong folder structure
• inconsistent naming

Explicit review rules prevent this.

When NOT To Use This

This approach is unnecessary for:

• very small repositories
• short-lived prototypes
• single-developer experiments

The overhead only pays off when:

• multiple developers collaborate
• AI agents are heavily used
• the project has architectural complexity.

How I Apply This in Real Projects

In projects where I use AI coding agents (primarily Claude-based tools, GPT assistants, and Gemini), I always start by creating a docs directory designed for the agent.

The process is simple:

1. Write a short product overview
2. Describe architecture at a high level
3. Define coding and testing rules
4. Document code review expectations
5. Outline future architectural plans

The two-week documentation effort I described at the beginning of this article wasn't typical — that was a rescue operation for a codebase that had already accumulated months of context-free AI changes. For a new project, the initial setup takes a day or two. After that, you maintain it incrementally.

The "find 20 components to fix" trick has become my standard smoke test for new documentation. If the agent can autonomously identify and fix real issues based on the context you've written, the documentation is working. If it makes the same mistakes as before, the docs are missing something important.

Practical Recommendations

If you want to try this approach:

Start small.

Create just four documents:

docs/product.md
docs/architecture.md
docs/coding-standards.md
docs/testing-strategy.md

Add an index file and reference it from your agent instructions.

Then gradually expand documentation as real problems appear.

Also remember:

• keep documents short
• keep them structured
• keep them updated.

Think of them as system prompts for your codebase.

Summary

The project where non-developers were writing code through AI taught me something fundamental: models are already good enough. The bottleneck isn't intelligence — it's context. An agent without project documentation will confidently produce code that breaks every convention you have. An agent with structured context will find and fix problems you didn't even ask about.

A structured docs/ directory can describe:

• product context
• architecture
• coding standards
• testing rules
• code review expectations
• future architectural plans

Combined with integrations like Jira and Git history, this gives agents enough context to generate code that aligns with real production systems.

In practice, this simple change dramatically improves the quality of AI-generated code. Two weeks of documentation saved me months of cleanup.

If you have feedback, alternative approaches, or just want to discuss this topic — feel free to reach out.

I was three weeks into a new client engagement — a mid-sized insurance company building a policy administration CRM from scratch. No legacy code, no inherited debt. Just a blank repo and a brief that said "build it right this time."

The first real decision hit before I wrote a single component. Not React vs. something else — that was settled. The question was: what handles routing? What handles server state? What handles forms? What handles client state? Each one is a separate choice. Each one affects the others.

I've been in that moment before. Different company, different domain, same paralysis. And I've watched teams make the same mistake each time: they pick tools independently, without thinking about how they work together. React Router because someone knows it. Redux Toolkit because it was used at the last job. React Hook Form because of a tutorial someone bookmarked. Three months in, you have routing that's loosely typed, server state duplicated in Redux, and form validation that doesn't talk to your query layer. The tools work in isolation. The system doesn't.

That insurance CRM was where I fully committed to TanStack as an ecosystem. Not because it was new. Because it was the most coherent answer I'd found to a question I'd been asking for years: how do these pieces actually fit together?

This is the first article in the React Playbook series — a hands-on guide to building production React apps with TanStack and a thoughtful architecture. We're starting here, at the beginning, because the choices you make in the first hour of a project shape everything that comes after.

What TanStack Actually Is

TanStack is a family of headless, framework-agnostic libraries maintained primarily by Tanner Linsley. The word family matters. These packages are designed to work independently — you can use TanStack Query with React Router, or TanStack Router with SWR — but they're built by the same team with consistent APIs, consistent TypeScript patterns, and a consistent philosophy about what a library should own vs. what your application should own.

The four packages that form the core of this series:

• TanStack Query — async state. Fetching, caching, background refetches, mutations, optimistic updates. It doesn't care how you fetch; it cares about what happens to the data after you fetch it.
• TanStack Router — type-safe routing. Every route param, every search param, every navigate call is typed against your actual route tree. No useParams<{ id: string }>() manual type assertions.
• TanStack Form — form state management. Headless, composable, works with any validation library. Deep integration with Query mutations comes naturally.
• TanStack Start — full-stack framework built on top of TanStack Router. SSR, server functions, streaming. We'll cover this in article #15. For now, know it exists.

What's not in TanStack: client state management — the kind of state that lives only in the browser and doesn't come from a server. For that, this series uses Reatom. I'll explain that choice properly in article #7. For now, note that useState and TanStack Query handle the vast majority of state in a typical app. Reatom enters the picture when you have genuinely complex reactive graphs.

The best stack isn't the one with the individually best tools. It's the one where the tools share a language.

Two Ways to Start

Option 1: Vite (SPA)

If you're building a client-rendered SPA — with a separate API, no SSR, no server functions — Vite is the starting point:

npm create vite@latest my-crm-app -- --template react-ts
cd my-crm-app
npm install

Then add the TanStack core:

npm install @tanstack/react-query @tanstack/react-router @tanstack/react-form
npm install -D @tanstack/router-devtools @tanstack/react-query-devtools

Add Zod for schema validation — it integrates directly with TanStack Form and pairs naturally with TypeScript:

npm install zod

That's the complete starting dependency set. Not ten packages. Five.

Option 2: TanStack Start (SSR / Full-stack)

If you need SSR, server functions, or want to colocate data fetching with your routes:

npx create-tsrouter-app@latest my-crm-app --template start-basic
cd my-crm-app
npm install

TanStack Start comes with React, TanStack Router, and Vinxi (the underlying build layer) preconfigured. You add TanStack Query and Form separately — same commands as above.

For the rest of this article — and the majority of this series — I'll use the Vite setup. We'll revisit TanStack Start in article #15 when we get to SSR and full-stack patterns.

The Router Setup

TanStack Router supports both file-based and code-based route definitions. I use code-based for new projects. It's more explicit, easier to understand when you're learning the ecosystem, and easier to refactor when your route tree changes.

Start by creating the route tree:

// src/router.ts
import { createRouter, createRoute, createRootRoute } from '@tanstack/react-router';
import { RootLayout } from './layouts/RootLayout';
import { DashboardPage } from './pages/DashboardPage';
import { PolicyListPage } from './pages/PolicyListPage';
import { PolicyDetailPage } from './pages/PolicyDetailPage';

const rootRoute = createRootRoute({
  component: RootLayout,
});

const dashboardRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: DashboardPage,
});

const policyListRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/policies',
  component: PolicyListPage,
});

const policyDetailRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/policies/$policyId',
  component: PolicyDetailPage,
});

const routeTree = rootRoute.addChildren([
  dashboardRoute,
  policyListRoute,
  policyDetailRoute,
]);

export const router = createRouter({ routeTree });

declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router;
  }
}

The Register declaration at the bottom is what makes everything type-safe. From this point forward, every useParams(), every <Link to="">, every navigate() call is checked against your actual route tree. If you rename $policyId to $id, TypeScript will tell you every single broken reference in the codebase. That's not a nice-to-have at scale. That's essential.

The App Entry Point

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { RouterProvider } from '@tanstack/react-router';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { router } from './router';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,
      retry: 1,
    },
  },
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  </React.StrictMode>,
);

Two decisions embedded here that are worth naming explicitly.

staleTime: 1000 * 60 * 5 — five minutes. By default, TanStack Query considers data stale immediately and refetches on every component mount and every window focus event. For a CRM where users navigate between the same policy records repeatedly, that's a lot of unnecessary network traffic. Five minutes as a global baseline is a reasonable starting point. You'll override it per-query when freshness matters more.

retry: 1 — retry failed requests once, not three times (the default). The default behavior means a failed API call spends up to 30 seconds retrying before your user sees an error. In a CRM, users notice latency. Fail fast, show the error, let the user decide whether to retry.

Your First Query

A policy list page. Here's what the data layer looks like end to end:

// src/api/policies.ts
import type { Policy } from '../types/policy';

export async function fetchPolicies(): Promise<Policy[]> {
  const res = await fetch('/api/policies');
  if (!res.ok) throw new Error(`Failed to fetch policies: ${res.status}`);
  return res.json();
}

// src/pages/PolicyListPage.tsx
import { useQuery } from '@tanstack/react-query';
import { Link } from '@tanstack/react-router';
import { fetchPolicies } from '../api/policies';

export function PolicyListPage() {
  const { data: policies, isLoading, isError } = useQuery({
    queryKey: ['policies'],
    queryFn: fetchPolicies,
  });

  if (isLoading) return <div>Loading policies...</div>;
  if (isError) return <div>Failed to load policies</div>;

  return (
    <ul>
      {policies.map((policy) => (
        <li key={policy.id}>
          <Link to="/policies/$policyId" params={{ policyId: policy.id }}>
            {policy.policyNumber}
          </Link>
        </li>
      ))}
    </ul>
  );
}

A few things worth making explicit.

queryKey: ['policies'] — this is the identity of the data. TanStack Query caches, deduplicates, and invalidates data by key. When you update a policy, you'll call queryClient.invalidateQueries({ queryKey: ['policies'] }) and this list will automatically refetch. The key design decision: keep keys predictable and structured. We'll go deep on key patterns in article #5.

<Link to="/policies/$policyId" params={{ policyId: policy.id }}> — fully type-checked. The to prop only accepts valid routes from your route tree. The params prop is typed to exactly what that route expects. You cannot pass a typo here and have it compile.

What You Don't Need Yet

I keep coming back to this piece of advice because I've seen it ignored repeatedly on greenfield projects.

Do not install:

• An i18n library until you actually have a second language requirement
• A component library until you understand your design system constraints
• A global state manager beyond useState until Query's cache isn't enough
• A charting library until you're building a chart
• An analytics package until the product is real

Every package you add before you need it is a decision made without enough information. The "complete stack" instinct — wanting to assemble everything before writing features — consistently results in wrong choices that are expensive to undo.

Honestly, the most common refactor I do on client codebases is removing things. Unused dependencies, abstractions that outlived their problems, config for features that were never built.

Start with the minimum. Add what you need when you need it.

Project Structure

Article #3 covers FSD (Feature-Sliced Design) properly, so I won't go deep here. But the starting skeleton that works for the first 20-30 features of any project:

src/
  api/            ← fetch functions, typed response shapes
  pages/          ← page-level components wired to routes
  layouts/        ← RootLayout, AuthedLayout, etc.
  components/     ← shared, reusable UI
  hooks/          ← shared React hooks
  types/          ← TypeScript interfaces and domain types
  router.ts       ← route tree definition
  main.tsx        ← app entry point

This structure is deliberately flat. It scales to about 25-30 features before it starts feeling crowded. At that point, you'll naturally feel the pull toward domain-based organization — and that's when FSD becomes the right tool. We'll get there.

Running It

npm run dev

You'll see two devtools panels appear: the TanStack Router devtools in the bottom corner and the React Query devtools floating panel. Both are worth learning. Router devtools shows your matched route, route params, and pending navigations. Query devtools shows every active query, its status, its data, its stale time, and lets you manually invalidate or refetch. Remove them for production by checking import.meta.env.DEV.

What Comes Next

This setup — Vite + TanStack Query + TanStack Router — is the foundation everything else in this series builds on. Over the next 29 articles:

• Article #2: TypeScript patterns specific to this stack — generics in query hooks, typed API layers, discriminated unions for UI states
• Article #3: FSD architecture — when the flat pages/ structure starts hurting and what replaces it
• Article #4: Error handling — Error Boundaries, query error states, global error strategies
• Article #7: Reatom — when your client state grows beyond what useState handles cleanly

The same QueryClient, the same router, the same project structure — growing incrementally instead of being replaced. That's the goal.

That insurance CRM shipped twelve months later. Four developers, significant business logic, a forms-heavy UI with dozens of policy types. The TanStack ecosystem handled all of it without once making us fight our own tools. That's the standard I hold stacks to: not "is it powerful," but "does it get out of the way."

If you're starting a new React project and want to talk through stack choices before committing — feel free to reach out. I've had this conversation more times than I can count and it rarely takes as long as people expect.

Static export remains the simplest deployment model for content-focused sites. This article documents the setup behind this very site — ma-x.im — a Next.js 15 project deployed to GitHub Pages.

Honestly, this was my first static export project. Vercel exists and it's free too. But I wanted something dead simple — no platform dependencies, no vendor lock-in, just push and it's live. GitHub Pages felt like the most boring choice possible, and that was exactly the point. A few weeks in, I'm genuinely happy with it. I don't think about deployments, I don't debug infrastructure, it just works. Sometimes the boring choice is the right one.

Context

The goal: a personal site with static content and a blog, deployed to GitHub Pages with a custom domain. Requirements are low ops overhead, no monthly costs, and good reliability. GitHub Pages handles all of this well for static content.

GitHub Pages constraints shape the architecture:

Static hosting only. No server-side rendering, no API routes that execute at runtime, no middleware. Everything must be pre-rendered at build time.

Project Page path prefix. If you deploy to https://<user>.github.io/<repo>/, all routes are prefixed with /<repo>/. This breaks absolute paths and requires explicit configuration. With a custom domain, this prefix disappears — the site serves at root.

No redirects or rewrites. GitHub Pages serves files as-is. You cannot configure server-side redirects. Client-side routing works, but direct navigation to a non-existent file returns GitHub's 404 page unless you provide a 404.html.

404 handling. GitHub Pages serves 404.html from the root when a file isn't found. Next.js static export generates this file from your not-found.tsx, but only if you have one.

Core Concept

Next.js SSG vs SSR/ISR

Next.js supports multiple rendering strategies. For GitHub Pages, only Static Site Generation (SSG) works:

• SSR (Server-Side Rendering): Renders pages on each request. Requires a Node.js server. Not compatible with static hosting.
• ISR (Incremental Static Regeneration): Pre-renders at build, then revalidates on a schedule. Requires a server. Not compatible with static hosting.
• SSG (Static Site Generation): Pre-renders all pages at build time. Outputs plain HTML/CSS/JS files. Works on any static host.

Static Export in Next.js 15

In Next.js 13+, static export is enabled via output: 'export' in your config. The build process generates a folder (default: out/) containing all HTML files, assets, and client-side JavaScript bundles.

This mode disables features that require a server runtime:

• API routes (unless they're static JSON files)
• Server Actions
• Middleware
• Dynamic rendering with cookies() or headers()
• Redirects and rewrites in next.config.ts
• Image Optimization API (requires a server)

basePath for Project Pages

When deploying to https://<user>.github.io/<repo>/, the site lives at a subpath, not root. Without configuration, asset URLs and links break:

Expected: /styles/main.css
Actual location: /<repo>/styles/main.css
→ 404

The basePath config prepends the prefix to all routes and asset imports:

// next.config.ts
const nextConfig: NextConfig = {
  basePath: '/my-repo',
  output: 'export',
};

Next.js automatically handles:

• <Link href="/about"> becomes /<repo>/about
• Static imports and public folder assets
• CSS/JS bundle paths

With a custom domain, basePath should not be set. The domain points directly to the repo's Pages site, so routes serve at root.

trailingSlash

Controls whether routes end with /:

• trailingSlash: false → /blog/my-post (outputs /blog/my-post.html)
• trailingSlash: true → /blog/my-post/ (outputs /blog/my-post/index.html)

GitHub Pages handles both, but trailingSlash: true is more predictable for some edge cases with direct file navigation. The trade-off is URL aesthetics. This repo uses false.

assetPrefix

Separate from basePath, assetPrefix controls where JS/CSS bundles are loaded from. Useful when assets are served from a CDN. For most GitHub Pages deployments, it's not needed — basePath handles everything.

next/image on Static Hosts

The default next/image component uses Next.js Image Optimization API, which requires a server. On static export, you must either:

1. Set images: { unoptimized: true } to disable optimization and use raw image URLs
2. Use a third-party loader (Cloudinary, Imgix, etc.)
3. Avoid next/image entirely and use <img> tags

This repo uses native <img> tags with a custom fallback wrapper, avoiding the issue entirely.

Implementation Example

1) Configure Next.js for static export (SSG)

The current next.config.ts in this repo:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  trailingSlash: false,
};

export default nextConfig;

This configuration:

• Enables static export to out/ directory
• Disables image optimization (required for static hosting)
• Uses clean URLs without trailing slashes

For a Project Page deployment (without custom domain), add basePath:

// Proposed change for Project Page deployment
const nextConfig: NextConfig = {
  output: 'export',
  basePath: '/ma-x.im', // Repository name
  images: {
    unoptimized: true,
  },
  trailingSlash: false,
};

Limitations to understand:

With output: 'export', these features throw build errors or are ignored:

• redirects and rewrites in config
• Middleware (middleware.ts)
• API routes with runtime logic
• Server Actions
• cookies(), headers(), searchParams in Server Components (without force-static)

2) Make routing and links survive basePath (Project Page)

The failure mode: During development, the site runs at localhost:3000/. Links like <Link href="/blog"> work. After deploying to https://user.github.io/repo/, the same link points to https://user.github.io/blog (missing the repo prefix), returning 404.

How Next.js handles it: When basePath is configured, next/link and next/router automatically prepend it. You don't need to change your code — just avoid hardcoded absolute paths.

From this repo's src/app/blog/page.tsx:

import Link from 'next/link';

// This works correctly with or without basePath
<Link href={\`/blog/\${post.id}\`}>
  <h2>{post.title}</h2>
</Link>

What breaks:

1. Hardcoded absolute paths in JavaScript/CSS:

// Bad: Ignores basePath
const logoUrl = '/images/logo.png';

// Good: Use relative paths or public folder imports
import logo from '@/public/images/logo.png';

2. Metadata URLs (OpenGraph, Twitter, canonical):

From this repo's src/app/blog/[slug]/page.tsx:

export async function generateMetadata({ params }: BlogPostPageProps): Promise<Metadata> {
  const { slug } = await params;
  const post = blogPosts.find((p) => p.id === slug);

  return {
    openGraph: {
      url: \`https://ma-x.im/blog/\${post.id}\`, // Hardcoded full URL
    },
  };
}

This works because the site uses a custom domain at root. For a Project Page, you'd need:

// Proposed change for Project Page
const BASE_URL = process.env.NEXT_PUBLIC_BASE_URL || 'https://user.github.io/repo';

url: \`\${BASE_URL}/blog/\${post.id}\`,

3. Sitemap and RSS links:

This repo generates a sitemap via app/sitemap.ts. All URLs must use the full absolute base. Note the export const dynamic = 'force-static' — it is required for output: 'export', otherwise the build fails:

// app/sitemap.ts
import type { MetadataRoute } from 'next';
import { blogPosts } from '@/data/posts';

export const dynamic = 'force-static';

const BASE_URL = 'https://ma-x.im';

export default function sitemap(): MetadataRoute.Sitemap {
  const posts = blogPosts.map((post) => ({
    url: \`\${BASE_URL}/blog/\${post.id}\`,
    lastModified: new Date(post.date),
    changeFrequency: 'monthly' as const,
    priority: 0.7,
  }));

  return [
    { url: BASE_URL, lastModified: new Date(), changeFrequency: 'monthly', priority: 1 },
    { url: \`\${BASE_URL}/blog\`, lastModified: new Date(), changeFrequency: 'weekly', priority: 0.8 },
    { url: \`\${BASE_URL}/contact\`, lastModified: new Date(), changeFrequency: 'yearly', priority: 0.5 },
    ...posts,
  ];
}

New blog posts are picked up automatically — the sitemap is built from the same blogPosts array used by the blog pages.

Pair the sitemap with app/robots.ts so search engines can discover it. Same rule applies — export const dynamic = 'force-static' is required:

// app/robots.ts
import type { MetadataRoute } from 'next';

export const dynamic = 'force-static';

export default function robots(): MetadataRoute.Robots {
  return {
    rules: {
      userAgent: '*',
      allow: '/',
    },
    sitemap: 'https://ma-x.im/sitemap.xml',
  };
}

3) Blog pipeline: Markdown + react-markdown (repo-specific)

This repo stores blog posts as TypeScript files with embedded markdown content, not as .md files. This approach has trade-offs:

Advantages:

• Type safety on post metadata
• No build-time file system reading
• Posts are bundled with the application

Disadvantages:

• Content editing requires code changes
• Larger JavaScript bundles if content grows
• No separation between content and code

Post structure in src/data/posts/types.ts:

export interface BlogPost {
  id: string;
  title: string;
  excerpt: string;
  tags: string[];
  date: string;
  readTime: string;
  content: string; // markdown content
}

Static route generation in src/app/blog/[slug]/page.tsx:

import { blogPosts } from '@/data/posts/index';

// Generate static pages for all posts at build time
export async function generateStaticParams() {
  return blogPosts.map((post) => ({
    slug: post.id,
  }));
}

// Return 404 for slugs not in the list (required for output: 'export')
export const dynamicParams = false;

The dynamicParams = false is critical. Without it, Next.js assumes dynamic routes might be handled at runtime — incompatible with static export.

Rendering markdown via src/components/MarkdownContent.tsx:

'use client';

import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';

export function MarkdownContent({ content }: { content: string }) {
  return (
    <ReactMarkdown
      remarkPlugins={[remarkGfm]}
      components={{
        code: ({ className, children, ...props }: any) => {
          const match = /language-(\w+)/.exec(className || '');
          const codeString = String(children).replace(/\n$/, '');

          if (match) {
            return (
              <SyntaxHighlighter style={oneDark} language={match[1]} PreTag="div">
                {codeString}
              </SyntaxHighlighter>
            );
          }

          return <code className="px-2 py-0.5 bg-gray-100 rounded text-sm" {...props}>{children}</code>;
        },
      }}
    >
      {content}
    </ReactMarkdown>
  );
}

Common pitfalls:

1. Missing generateStaticParams: Dynamic routes without static params fail on export with a build error.

2. Forgetting dynamicParams = false: The build succeeds, but routes not in generateStaticParams cause errors.

3. Runtime file system access: If you read .md files with fs, ensure it happens only in generateStaticParams or generateMetadata, not in component render functions. In App Router, this works correctly since those functions run at build time.

4. Syntax highlighter SSR issues: Libraries like react-syntax-highlighter can have hydration mismatches. Marking the component with 'use client' and ensuring consistent rendering helps.

4) GitHub Actions deployment to GitHub Pages

The existing workflow at .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [master, new-version-v2]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npx tsc --noEmit

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Key elements:

1. Permissions: pages: write and id-token: write are required for the official deploy action. contents: read allows checkout.
2. Lint and type check before build: Catches issues before producing artifacts. Lint validates code style, tsc --noEmit verifies types without emitting files.
3. Concurrency: Prevents overlapping deployments with cancel-in-progress: false (lets the current deployment finish rather than canceling mid-deploy).
4. Artifact upload: The upload-pages-artifact action packages ./out (Next.js static export directory) for deployment.
5. Two-job structure: Build and deploy are separate jobs. The deploy job waits for build with needs: build.
6. Environment: The github-pages environment enables GitHub's deployment tracking and status checks.

Repo settings checklist:

1. Navigate to repository Settings → Pages
2. Under "Build and deployment", set Source to "GitHub Actions"
3. Do not select a branch — the workflow handles deployment
4. If using a custom domain, enter it under "Custom domain"
5. Enforce HTTPS (checkbox)

5) Custom domain on GitHub Pages

This repo uses the custom domain ma-x.im. Setup involves three parts:

1. CNAME file in the repository:

The file public/CNAME contains:

ma-x.im

This file must exist in the deployed output. Since it's in public/, Next.js copies it to out/ during build. The GitHub Pages deploy action then includes it in the deployment artifact.

2. Repository settings:

In Settings → Pages → Custom domain, enter ma-x.im. GitHub validates DNS and provisions an SSL certificate.

3. DNS configuration:

For an apex domain like ma-x.im, configure DNS at your registrar:

Option A: A records (IPv4)

A     @     185.199.108.153
A     @     185.199.109.153
A     @     185.199.110.153
A     @     185.199.111.153

Option B: ALIAS/ANAME record (if supported)

ALIAS    @    <user>.github.io

For a subdomain like www.ma-x.im:

CNAME    www    <user>.github.io

HTTPS certificate provisioning:

After DNS propagates, GitHub automatically requests a certificate from Let's Encrypt. This can take minutes to hours depending on DNS propagation. During this time, the site may show a certificate warning.

Keeping CNAME stable:

The current setup (CNAME in public/) works correctly. An alternative for repos where you can't commit to public/:

      - name: Build
        run: npm run build

      - name: Add CNAME
        run: echo "ma-x.im" > ./out/CNAME

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

6) Local verification and "it works on my machine" traps

After building, verify the static output locally:

# Build the site
npm run build

# Serve the output directory
npx serve out

This serves at http://localhost:3000 by default. All routes should work, including direct navigation to /blog/building-design-systems-that-scale.

Testing basePath locally:

If deploying as a Project Page with basePath: '/my-repo', the local test needs to simulate the path prefix:

npx serve out -l 3000
# Then access at http://localhost:3000/my-repo/

"Works locally, broken in production" scenarios:

1. Missing CNAME: Site deploys but custom domain doesn't work.
2. Absolute paths in code: Work at root locally, break with basePath or different domain.
3. Environment variables: NEXT_PUBLIC_* variables are baked in at build time. If you test with .env.local but CI doesn't have the same values, behavior differs.
4. Browser caching: Hard refresh or incognito mode when debugging deployment issues.

Where It Breaks in Enterprise

Static export works for content sites but hits walls in enterprise contexts:

No server features. Auth, personalization, A/B testing, and anything requiring runtime logic must move to external services or client-side JavaScript.

Preview and drafts. Editorial workflows typically need preview deployments of unpublished content. Static export requires rebuilding for every preview — doable but slow.

Search. Client-side search works for small sites (load a JSON index, search in JavaScript). For larger content, you need an external search service.

Comments. Disqus, Giscus, or similar third-party embeds. No server means no self-hosted comment storage.

Build time scaling. As content grows, build times grow. A 1000-post blog might take 10+ minutes to build. This is manageable but affects development velocity.

Image optimization. Without the Next.js optimization API, you handle image resizing externally or serve unoptimized assets. On fast connections, this is fine. On mobile, it hurts.

Multi-locale with basePath. Supporting multiple languages with static export works but gets complex with custom domains per locale or locale prefixes combined with basePath.

Analytics and privacy. Client-side analytics (Google Analytics, Plausible) work. Server-side analytics (for privacy) require a proxy or separate service.

Common Mistakes

Forgetting basePath for Project Pages. Routes and assets return 404. The site looks broken on GitHub but works locally.

Using next/image without unoptimized: true. Build fails with an error about Image Optimization requiring a server.

Expecting redirects/rewrites to work. They're silently ignored on static export. Use client-side navigation or restructure URLs.

Missing generateStaticParams for dynamic routes. Build error: "Page with output: export has dynamic route but no generateStaticParams."

Using dynamicParams = true with static export. Build might succeed but unknown slugs cause issues. Always set dynamicParams = false.

Runtime environment variables. process.env.MY_VAR in client components doesn't work — it's replaced at build time. Use NEXT_PUBLIC_ prefix for client-visible values.

Deploying the wrong folder. Next.js outputs to out/ by default, but if you forget to check the workflow, you might deploy .next/ or the root folder.

Broken canonical/OG URLs. Hardcoded URLs that don't account for basePath or custom domain result in wrong social previews and SEO issues.

When NOT To Use This

Static export to GitHub Pages is wrong when:

• You need authentication or user sessions
• Content is personalized per user
• You need middleware (geo-redirects, A/B tests at the edge)
• You need API routes with runtime logic
• Build times exceed acceptable CI limits (hundreds of pages or more)
• You need ISR for frequently changing content

For these cases, consider Vercel, Netlify, or Cloudflare Pages — platforms with server/edge support that handle these features natively with Next.js.

How I Apply This in Real Projects

For personal sites and blogs, I keep the stack minimal: static export, GitHub Pages, and a custom domain. No external services beyond what's required.

I automate the deployment pipeline once and don't touch it. The workflow in this repo hasn't changed significantly since initial setup.

I intentionally don't build: comments, search (for small sites), analytics (unless required), or complex CMS integrations. Each adds maintenance burden disproportionate to value for personal projects.

When a project genuinely needs server features, I move to a platform that supports them rather than working around static export limitations.

Practical Recommendations

Config checklist:

• output: 'export' in next.config.ts
• basePath set if deploying to /<repo>/ (omit for custom domain)
• images: { unoptimized: true } if using next/image
• trailingSlash set based on URL preference
• dynamicParams = false on all dynamic routes

Content pipeline:

• generateStaticParams returns all valid slugs
• Metadata URLs use full absolute URLs for social sharing
• CNAME file in public/ for custom domains

CI/CD checks:

• Lint runs before build (npm run lint)
• Type check runs before build (npx tsc --noEmit)
• Build artifact is correct directory (out/)
• Workflow triggers on correct branches

Regression tests:

• Manually verify a few routes after deployment
• Check 404 page appears for invalid routes
• Verify assets load (images, CSS, JS)
• Test OG images in social share debuggers

Summary

Next.js static export to GitHub Pages is a production-ready approach for content sites. It's what powers this site, and after running it for a while I can say the setup is genuinely low-maintenance.

The key decisions — output: 'export', images: { unoptimized: true }, generateStaticParams with dynamicParams = false — address the common failure modes. Understanding the constraints (no server runtime, basePath for Project Pages, explicit static generation for dynamic routes) saves you from most surprises.

The approach scales well for small to medium sites. For larger content needs or server-dependent features, migration to a full hosting platform is the right move rather than fighting static export limitations.

If you have feedback, alternative approaches, or just want to discuss this topic — feel free to reach out.

At Motorola Solutions I walked into a codebase with hundreds of internal projects. Every team followed the brand book — in theory. In practice, it was chaos. Buttons looked different everywhere. Navigation behaved differently in every app. Everyone thought they were on-brand. Nobody actually was.

They asked me to help build a unified design system. Nine months of work, tight collaboration between designers and developers. The result: a component library that snapped together like Lego. You didn't think about padding, font sizes, spacing — everything just worked out of the box. We shipped variants for React and Angular simultaneously. The designers had specced the components so precisely that they composed into each other without friction.

Then came adoption. Migration was painful. Versioning became its own nightmare — but I'll get to that.

Building a design system is the easy part. Getting teams to actually use it is where most fail.

The Problem

I've watched multiple design system efforts die. Not because the components were poorly designed, but because they didn't solve the right problems at the right time. Teams would build beautiful libraries, document everything meticulously, and then watch as nobody used them.

Start with Real Problems

The best design systems I've built started with actual pain points:

• Inconsistent UI patterns across features
• Slow feature development due to rebuilding common components
• Accessibility gaps that were hard to track
• Design-dev handoff friction that slowed everything down

Key Principles

1. Component API Design Matters

Your components should be easy to use correctly and hard to use incorrectly.

// Bad: Too many props, unclear usage
<Button 
  variant="primary" 
  size="md" 
  loading={false} 
  disabled={false}
  onClick={handleClick}
/>

// Good: Clear defaults, composable
<Button onClick={handleClick}>
  Click me
</Button>

<Button variant="secondary" loading>
  Loading...
</Button>

2. Documentation is Your Product

Nobody reads long documentation. Make it:

• Visual - Show examples first
• Interactive - Let people play with props
• Searchable - Find what you need fast
• Practical - Real use cases, not toy examples

I use Storybook for this. Every component gets:

• Multiple usage examples
• Props documentation
• Accessibility notes
• Do's and don'ts

3. Build for Adoption

The best design system is the one people use. Focus on:

Developer Experience:

• TypeScript support out of the box
• Clear error messages
• Intuitive prop names
• Good defaults

Performance:

• Tree-shakeable exports
• Lazy loading for heavy components
• Optimized bundle size

Flexibility:

• Composable components
• Escape hatches when needed
• Theme customization

The Tech Stack

Here's what I typically use:

• React + TypeScript - Type safety is non-negotiable
• Tailwind CSS - Utility-first scaling, easy theming
• Radix UI - Accessible primitives
• Storybook - Component documentation
• Turborepo - Monorepo management
• Changesets - Version management

Common Pitfalls

Over-engineering Early

Don't build 50 components on day one. Start with:

1. Buttons
2. Inputs
3. Layout primitives
4. Typography system

Add more as real needs emerge.

Ignoring Migration Path

At Motorola Solutions, migration was the hardest part. Hundreds of projects, each with their own component variations. We couldn't flip a switch. Some teams adopted early, others dragged their feet for months. Eventually every project had the same interface, the same navigation, the same look — and honestly, that felt great. But then versioning caught up with us: some teams locked to an early version and never updated. When they finally did — months later — things broke because the API had evolved. We spent weeks helping teams catch up. If I could redo one thing, it would be investing more in automated migration tooling from day one.

If you're replacing an old system, make migration gradual:

• Support both old and new side-by-side
• Provide codemods where possible
• Document migration guides
• Track adoption metrics

Skipping Accessibility

Build it in from day one. Every component should:

• Work with keyboard navigation
• Have proper ARIA labels
• Support screen readers
• Handle focus management

Measuring Success

Track these metrics:

1. Adoption rate - % of features using the system
2. Component coverage - % of UI built with system components
3. Development velocity - Time to build new features
4. Consistency score - How many UI patterns exist

Conclusion

After the Motorola Solutions project, I started seeing design systems differently. The system itself isn't the product — adoption is the product. The best component library in the world is worthless if teams work around it instead of using it. Ours was far from perfect, but it worked because designers and developers built it together, and because the components were genuinely easier to use than rolling your own.

Start small. Iterate based on real feedback from real teams. And always prioritize the developer experience — because if it's easier to build from scratch than to use your system, that's exactly what people will do.

Have questions about building design systems? Reach out — I've been through this and happy to share more.

I remember the exact moment I realized I couldn't go back. I had been writing TypeScript for a while, got used to it, and then joined a project that was pure JavaScript. No types. No autocompletion for props. No compile-time errors. Just... hope.

It was unbearable. How do you know what this function returns? You don't — you read the implementation. What props does this component accept? You check the source. Did someone rename a field in the API response? You'll find out in production.

The thing about TypeScript is that you don't see the bugs it prevents. You introduce strict types and your code just... works more reliably. You never get the dramatic "TypeScript saved us from a production outage" moment because the bug never made it past your editor. It stays invisible. But go back to a project without it, and you feel the absence immediately.

TypeScript isn't just about catching bugs. It's about building systems that are impossible to misuse.

Why Type Safety Matters

After 20+ years of engineering, I've learned: the best code is code that guides you toward correct usage.

The Cost of Runtime Errors

Runtime errors in production are expensive:

• User frustration - Broken features hurt trust
• Debug time - Finding issues in production is slow
• Lost revenue - Crashes during checkout cost money
• Team velocity - Fear of breaking things slows development

TypeScript moves these errors to compile time.

Architecture Patterns

1. Strict Type Configuration

Start with the strictest possible tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}

Yes, it's painful at first. But it catches so many bugs.

2. Component Props as Contracts

Your component props are API contracts:

// Weak typing
interface ButtonProps {
  variant?: string;
  size?: string;
  onClick?: Function;
}

// Strong typing
type ButtonVariant = "primary" | "secondary" | "ghost";
type ButtonSize = "sm" | "md" | "lg";

interface ButtonProps {
  variant?: ButtonVariant;
  size?: ButtonSize;
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  children: React.ReactNode;
}

Now your IDE will autocomplete variants and catch typos.

3. Discriminated Unions for State

Handle complex state with discriminated unions:

type FetchState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

function UserProfile() {
  const [state, setState] = useState<FetchState<User>>({
    status: "idle",
  });

  // TypeScript knows what properties exist in each branch
  if (state.status === "success") {
    return <div>{state.data.name}</div>; // ✅ data exists
  }

  if (state.status === "error") {
    return <div>{state.error.message}</div>; // ✅ error exists
  }

  return <Loading />;
}

This pattern eliminates entire classes of bugs.

4. Generic Components Done Right

Make your components reusable without losing type safety:

interface SelectOption<T> {
  value: T;
  label: string;
}

interface SelectProps<T> {
  options: SelectOption<T>[];
  value: T;
  onChange: (value: T) => void;
}

function Select<T>({ options, value, onChange }: SelectProps<T>) {
  return (
    <select
      value={String(value)}
      onChange={(e) => {
        const option = options.find(
          (opt) => String(opt.value) === e.target.value
        );
        if (option) onChange(option.value);
      }}
    >
      {options.map((opt) => (
        <option key={String(opt.value)} value={String(opt.value)}>
          {opt.label}
        </option>
      ))}
    </select>
  );
}

// Usage - fully type-safe!
<Select<UserRole>
  options={[
    { value: "admin", label: "Admin" },
    { value: "user", label: "User" },
  ]}
  value={role}
  onChange={setRole} // TypeScript knows this is UserRole
/>

5. Form Validation with Zod

Combine React Hook Form with Zod for bulletproof forms:

import { z } from "zod";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

const userSchema = z.object({
  email: z.string().email("Invalid email"),
  age: z.number().min(18, "Must be 18+"),
  role: z.enum(["admin", "user"]),
});

type UserFormData = z.infer<typeof userSchema>;

function UserForm() {
  const { register, handleSubmit, formState: { errors } } = 
    useForm<UserFormData>({
      resolver: zodResolver(userSchema),
    });

  const onSubmit = (data: UserFormData) => {
    // data is fully typed and validated!
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} />
      {errors.email && <span>{errors.email.message}</span>}
    </form>
  );
}

One schema, both runtime validation and TypeScript types.

API Integration

Type your API responses:

// Define your API types
interface User {
  id: string;
  name: string;
  email: string;
}

interface ApiResponse<T> {
  data: T;
  error?: string;
}

// Type-safe API client
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const json: ApiResponse<User> = await response.json();
  
  if (json.error) {
    throw new Error(json.error);
  }
  
  return json.data;
}

// Use with TanStack Query
const { data: user } = useQuery({
  queryKey: ["user", id],
  queryFn: () => fetchUser(id),
});

// user is typed as User | undefined

Testing Benefits

TypeScript makes testing easier:

import { render, screen } from "@testing-library/react";

// TypeScript catches missing props
render(<Button>Click me</Button>); // ✅

// @ts-expect-error - variant must be valid
render(<Button variant="invalid">Click me</Button>); // ❌

Developer Experience Wins

With proper TypeScript setup:

1. Refactoring is safe - Rename a prop, find all usages instantly
2. Autocomplete everywhere - Your IDE knows what's valid
3. Self-documenting code - Types explain usage
4. Faster onboarding - New devs understand APIs from types
5. Fewer PR comments - Type checker catches issues

Common Mistakes

Using any

Never use any. Use unknown if you must:

// Bad
function processData(data: any) {
  return data.value; // No safety
}

// Good
function processData(data: unknown) {
  if (typeof data === "object" && data !== null && "value" in data) {
    return (data as { value: string }).value;
  }
  throw new Error("Invalid data");
}

Ignoring Errors

Don't @ts-ignore your way out of problems. Fix the types.

Over-complicating Types

Keep it simple. Complex types are hard to maintain.

Conclusion

Every time I join a project that doesn't have TypeScript, my first instinct is to add it. Not because I enjoy configuring tsconfig.json — but because I've experienced the difference too many times. The bugs you don't see. The refactors that just work. The onboarding where new developers understand APIs from reading types instead of hoping.

Type safety isn't optional for serious React applications. It's the foundation of reliable software, great DX, and confident refactoring. Invest in your type system. Your future self will thank you.

Want to discuss TypeScript architecture? Let's connect.

At Motorola Solutions I built a multi-step contract wizard where users selected products, services, additional options, and pricing tiers — dozens of fields that depended on each other. It wasn't just a form. It was a live calculator that recalculated totals, toggled conditional sections, and validated business rules at every step.

Later, at an insurance company, I worked on a policy builder that asked everything from property type and vehicle model to how many pets you own and how long you've had them. Every answer changed what came next. Every combination produced a different quote.

Forms like these are where most implementations fall apart. A simple login form? Easy. A multi-step wizard with conditional fields, async validation, dynamic pricing, and file uploads? That's a different engineering problem entirely.

The Challenge

Complex forms have multiple concerns:

• State management - Field values, touched, dirty states
• Validation - Sync and async, field-level and form-level
• UX - When to show errors, loading states, success feedback
• Performance - Re-renders, large forms, dynamic fields
• Accessibility - Screen readers, keyboard navigation, error announcements

The Right Tools

After building dozens of complex forms, here's my stack:

• React Hook Form - Uncontrolled forms, great performance
• Zod - Schema validation, type inference
• TanStack Query - Async validation, mutations
• Radix UI - Accessible form primitives

Architecture Patterns

1. Schema-First Design

Define your form schema first:

import { z } from "zod";

const addressSchema = z.object({
  street: z.string().min(1, "Street is required"),
  city: z.string().min(1, "City is required"),
  country: z.string().min(1, "Country is required"),
  postalCode: z.string().regex(/^d{5}$/, "Invalid postal code"),
});

const userSchema = z.object({
  email: z.string().email("Invalid email"),
  password: z
    .string()
    .min(8, "At least 8 characters")
    .regex(/[A-Z]/, "Need uppercase letter")
    .regex(/[0-9]/, "Need a number"),
  confirmPassword: z.string(),
  address: addressSchema,
  terms: z.literal(true, {
    errorMap: () => ({ message: "You must accept terms" }),
  }),
}).refine((data) => data.password === data.confirmPassword, {
  message: "Passwords don't match",
  path: ["confirmPassword"],
});

type UserFormData = z.infer<typeof userSchema>;

One schema defines:

• Field types
• Validation rules
• Error messages
• TypeScript types

2. Async Validation

Check email availability without blocking the UI:

const emailSchema = z.string().email().refine(
  async (email) => {
    const response = await fetch(`/api/check-email?email=${email}`);
    const { available } = await response.json();
    return available;
  },
  { message: "Email already taken" }
);

With React Hook Form:

<input
  {...register("email", {
    validate: async (value) => {
      const result = await emailSchema.safeParseAsync(value);
      return result.success || result.error.errors[0].message;
    },
  })}
/>

3. Multi-Step Forms

Break complex forms into steps:

function MultiStepForm() {
  const [step, setStep] = useState(1);
  const methods = useForm<UserFormData>();

  const onSubmit = async (data: UserFormData) => {
    if (step < 3) {
      setStep(step + 1);
      return;
    }

    // Final submission
    await createUser(data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        {step === 1 && <PersonalInfoStep />}
        {step === 2 && <AddressStep />}
        {step === 3 && <ReviewStep />}

        <div>
          {step > 1 && (
            <button type="button" onClick={() => setStep(step - 1)}>
              Back
            </button>
          )}
          <button type="submit">
            {step < 3 ? "Next" : "Submit"}
          </button>
        </div>
      </form>
    </FormProvider>
  );
}

4. Dynamic Field Arrays

Add/remove fields dynamically:

import { useFieldArray } from "react-hook-form";

function SkillsForm() {
  const { control, register } = useForm();
  const { fields, append, remove } = useFieldArray({
    control,
    name: "skills",
  });

  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input
            {...register(`skills.${index}.name`)}
            placeholder="Skill name"
          />
          <input
            type="number"
            {...register(`skills.${index}.years`)}
            placeholder="Years"
          />
          <button type="button" onClick={() => remove(index)}>
            Remove
          </button>
        </div>
      ))}
      
      <button
        type="button"
        onClick={() => append({ name: "", years: 0 })}
      >
        Add Skill
      </button>
    </div>
  );
}

5. Conditional Fields

Show/hide fields based on other values:

function PaymentForm() {
  const { register, watch } = useForm();
  const paymentMethod = watch("paymentMethod");

  return (
    <div>
      <select {...register("paymentMethod")}>
        <option value="card">Credit Card</option>
        <option value="bank">Bank Transfer</option>
      </select>

      {paymentMethod === "card" && (
        <>
          <input {...register("cardNumber")} placeholder="Card Number" />
          <input {...register("cvv")} placeholder="CVV" />
        </>
      )}

      {paymentMethod === "bank" && (
        <>
          <input {...register("accountNumber")} placeholder="Account" />
          <input {...register("routingNumber")} placeholder="Routing" />
        </>
      )}
    </div>
  );
}

Error Handling UX

Show errors at the right time:

function SmartInput({ name, label, ...props }) {
  const {
    register,
    formState: { errors, touchedFields, isSubmitted },
  } = useFormContext();

  const error = errors[name];
  const showError = error && (touchedFields[name] || isSubmitted);

  return (
    <div>
      <label htmlFor={name}>{label}</label>
      <input
        id={name}
        aria-invalid={showError ? "true" : "false"}
        aria-describedby={showError ? `${name}-error` : undefined}
        {...register(name)}
        {...props}
      />
      {showError && (
        <span id={`${name}-error`} role="alert">
          {error.message}
        </span>
      )}
    </div>
  );
}

Only show errors after:

1. User has touched the field, OR
2. Form has been submitted

This prevents angry red errors while typing.

Performance Optimization

For large forms (50+ fields):

const { register } = useForm({
  mode: "onBlur", // Validate on blur, not on change
  shouldUnregister: true, // Unregister unmounted fields
});

Use Controller only for complex inputs:

import { Controller } from "react-hook-form";

<Controller
  name="birthDate"
  control={control}
  render={({ field }) => (
    <DatePicker
      value={field.value}
      onChange={field.onChange}
    />
  )}
/>

File Uploads

Handle files properly:

function FileUpload() {
  const { register, watch } = useForm();
  const file = watch("avatar");

  return (
    <div>
      <input
        type="file"
        accept="image/*"
        {...register("avatar")}
      />
      {file?.[0] && (
        <img
          src={URL.createObjectURL(file[0])}
          alt="Preview"
        />
      )}
    </div>
  );
}

Submission with TanStack Query

Clean mutation handling:

function UserForm() {
  const methods = useForm<UserFormData>();
  const mutation = useMutation({
    mutationFn: createUser,
    onSuccess: () => {
      toast.success("User created!");
      methods.reset();
    },
    onError: (error) => {
      toast.error(error.message);
    },
  });

  const onSubmit = (data: UserFormData) => {
    mutation.mutate(data);
  };

  return (
    <form onSubmit={methods.handleSubmit(onSubmit)}>
      {/* fields */}
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Saving..." : "Save"}
      </button>
    </form>
  );
}

Accessibility Checklist

✅ Labels for every input ✅ Error messages announced to screen readers ✅ Keyboard navigation works ✅ Focus management (auto-focus first error) ✅ Required fields marked ✅ Clear validation feedback

Testing

Test forms thoroughly:

import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

test("shows validation errors", async () => {
  render(<UserForm />);
  
  const user = userEvent.setup();
  const submitButton = screen.getByRole("button", { name: /submit/i });
  
  await user.click(submitButton);
  
  await waitFor(() => {
    expect(screen.getByText(/email is required/i)).toBeInTheDocument();
  });
});

Conclusion

The Motorola contract wizard and the insurance policy builder taught me the same lesson: complex forms aren't a UI problem — they're a data modeling problem. Get the schema right first, handle validation at the schema level, and the rest follows.

Schema-first validation. Smart error timing. Performance-aware rendering. Accessibility from day one. Thorough testing. Get these right, and even the most complex forms become manageable.

Need help with complex forms? Get in touch.

I joined a large Canadian automotive company as one of three senior frontend engineers. The site was public-facing — a product catalog where users browsed vehicle models, configurations, and pricing. Built on Sitecore with React components on top.

The first thing I noticed: the catalog page re-rendered on every interaction. Not just the part you touched — everything. The page pulled data from separate endpoints for vehicle types, models, specifications, and pricing. Every state change triggered a cascade of re-renders across all of them. It was the first time in my career I saw genuine, visible lag on a production public website — not some internal admin panel, but a site real customers used every day.

That became our first priority. We spent weeks profiling, restructuring data flow, and in some cases rewriting components from scratch because the original code was unsalvageable. The performance boost was dramatic and became our biggest early win with the team.

That experience taught me something I keep coming back to: performance isn't about premature optimization. It's about building systems that stay fast as they grow.

When to Optimize

Don't optimize everything. Optimize when:

• Users report slowness
• Metrics show issues (Core Web Vitals)
• Profiling reveals bottlenecks
• You're building data-heavy features

Measure first, optimize second.

Profiling Tools

Use the right tools:

1. React DevTools Profiler - See component render times
2. Chrome Performance - Analyze full page performance
3. Web Vitals - Track real user metrics
4. Lighthouse - Automated audits

Common Performance Issues

1. Unnecessary Re-renders

Problem: Component re-renders when props haven't changed.

// Bad: Creates new object every render
function Parent() {
  return <Child config={{ theme: "dark" }} />;
}

// Good: Stable reference
const CONFIG = { theme: "dark" };

function Parent() {
  return <Child config={CONFIG} />;
}

// Or use useMemo for dynamic values
function Parent() {
  const config = useMemo(() => ({ theme: "dark" }), []);
  return <Child config={config} />;
}

Use React.memo wisely:

const ExpensiveComponent = React.memo(({ data }) => {
  // Heavy rendering logic
  return <div>{/* ... */}</div>;
});

2. Large Lists Without Virtualization

Problem: Rendering 10,000 rows kills performance.

Solution: Use virtualization.

import { useVirtualizer } from "@tanstack/react-virtual";

function VirtualList({ items }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
  });

  return (
    <div ref={parentRef} style={{ height: "500px", overflow: "auto" }}>
      <div
        style={{
          height: `${virtualizer.getTotalSize()}px`,
          position: "relative",
        }}
      >
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.index}
            style={{
              position: "absolute",
              top: 0,
              left: 0,
              width: "100%",
              height: `${virtualRow.size}px`,
              transform: `translateY(${virtualRow.start}px)`,
            }}
          >
            {items[virtualRow.index].name}
          </div>
        ))}
      </div>
    </div>
  );
}

Only renders visible items. Huge performance win.

3. Heavy Computations in Render

Problem: Expensive calculations on every render.

// Bad: Recalculates every render
function DataTable({ data }) {
  const sorted = data.sort((a, b) => a.value - b.value);
  const filtered = sorted.filter(item => item.active);
  
  return <Table data={filtered} />;
}

// Good: Memoized
function DataTable({ data }) {
  const processed = useMemo(() => {
    const sorted = [...data].sort((a, b) => a.value - b.value);
    return sorted.filter(item => item.active);
  }, [data]);
  
  return <Table data={processed} />;
}

4. Inline Functions as Props

Problem: New function every render = child re-renders.

// Bad
function Parent() {
  return (
    <Child onClick={() => console.log("clicked")} />
  );
}

// Good
function Parent() {
  const handleClick = useCallback(() => {
    console.log("clicked");
  }, []);
  
  return <Child onClick={handleClick} />;
}

5. Context Provider Re-renders

Problem: Context value changes = all consumers re-render.

// Bad: New object every render
function ThemeProvider({ children }) {
  const [theme, setTheme] = useState("light");
  
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

// Good: Memoized value
function ThemeProvider({ children }) {
  const [theme, setTheme] = useState("light");
  
  const value = useMemo(() => ({ theme, setTheme }), [theme]);
  
  return (
    <ThemeContext.Provider value={value}>
      {children}
    </ThemeContext.Provider>
  );
}

Code Splitting

Load code only when needed:

import { lazy, Suspense } from "react";

const Dashboard = lazy(() => import("./Dashboard"));
const Settings = lazy(() => import("./Settings"));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  );
}

Image Optimization

Images are usually the biggest assets:

// Use modern formats
<img
  src="hero.webp"
  srcSet="hero-sm.webp 400w, hero-md.webp 800w, hero-lg.webp 1200w"
  sizes="(max-width: 640px) 400px, (max-width: 1024px) 800px, 1200px"
  alt="Hero"
  loading="lazy"
/>

Use loading="lazy" for below-the-fold images.

State Management Performance

Use Zustand for Better Performance

import { create } from "zustand";

const useStore = create((set) => ({
  todos: [],
  addTodo: (todo) => set((state) => ({
    todos: [...state.todos, todo]
  })),
}));

// Only re-renders when todos change
function TodoList() {
  const todos = useStore((state) => state.todos);
  return <div>{/* ... */}</div>;
}

// Never re-renders
function AddTodo() {
  const addTodo = useStore((state) => state.addTodo);
  return <button onClick={() => addTodo({ text: "New" })}>Add</button>;
}

TanStack Query for Server State

const { data } = useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  staleTime: 5 * 60 * 1000, // 5 minutes
});

Automatic caching, deduplication, background refetching.

Bundle Size Optimization

Tree Shaking

// Bad: Imports entire library
import _ from "lodash";

// Good: Import only what you need
import debounce from "lodash/debounce";

Analyze Bundle

npm install --save-dev vite-plugin-bundle-analyzer

Find and remove large dependencies.

React Compiler (Coming Soon)

React 19+ will have automatic memoization. But until then, manual optimization is needed.

Performance Checklist

✅ Profile before optimizing ✅ Use React.memo for expensive components ✅ Virtualize large lists ✅ Code split routes ✅ Lazy load images ✅ Optimize images (WebP, sizing) ✅ Memoize expensive computations ✅ Use proper state management ✅ Analyze bundle size ✅ Monitor Core Web Vitals

Conclusion

After the automotive catalog project, I never look at performance the same way. When it's bad, users feel it immediately — and they leave. When you fix it, the numbers speak for themselves. Every project where I've invested in performance early paid it back many times over.

Measure with real tools. Profile before you guess. Fix the actual bottlenecks, not the ones you imagine. And keep monitoring in production — performance degrades silently if nobody's watching.

Need help with React performance? Let's talk.

I learned to love monorepos the hard way — by suffering through the alternative.

At a large Canadian automotive company, we had a repository for basic UI components, a separate repository for complex components that depended on them, and then six separate repositories — one for each product line: cars, motorcycles, engines, marine, power equipment, and more. Plus utility repos for shared configs, linting rules, and deployment scripts.

When you released a patch to the base components, the chain reaction began. Update base components, then update complex components, then update all six product repos. Something always broke somewhere in that chain. A CI job would hang. A version mismatch would surface. A team using an older version would suddenly discover their build was broken. We outsourced CI/CD to external contractors, which added another layer of friction — every issue turned into a cross-team investigation.

We even started preparing a plan to consolidate everything into a single monorepo. I left the company before they finished.

That experience made me a firm believer: if your projects share code, put them together.

Why Monorepo?

Benefits:

• Shared code — one source of truth for components, utils
• Atomic changes — update library and consumers in one PR
• Better refactoring — see all usages across projects
• Unified tooling — one config for linting, testing, building
• Easier onboarding — everything in one repo

Drawbacks:

• Slower CI if not optimized
• More complex tooling needed
• Harder access control (everything visible)

For most teams, benefits outweigh drawbacks. And for teams that have lived through multi-repo dependency hell — it's not even a question.

Tools

I use Turborepo. It's fast, simple, and works great with npm/pnpm.

Alternatives:

• Nx - More features, steeper learning curve
• Lerna - Older, less maintained
• Rush - Microsoft's tool, great for large teams

Structure

Clean structure is critical:

my-monorepo/
├── apps/
│   ├── web/              # Main web app
│   ├── admin/            # Admin dashboard
│   └── mobile/           # React Native app
├── packages/
│   ├── ui/               # Shared component library
│   ├── utils/            # Shared utilities
│   ├── config/           # Shared configs (eslint, ts)
│   └── types/            # Shared TypeScript types
├── tooling/
│   ├── eslint-config/
│   └── typescript-config/
├── package.json
├── turbo.json
└── pnpm-workspace.yaml

Apps = Deployable applications Packages = Shared libraries Tooling = Dev tools and configs

Package Setup

Each package has its own package.json:

{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts",
    "./button": "./src/button.tsx"
  }
}

Apps import packages:

import { Button } from "@repo/ui";
import { formatDate } from "@repo/utils";

TypeScript resolves these via workspace protocol.

Turborepo Configuration

turbo.json:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["^build"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Key features:

• dependsOn - Build dependencies first
• outputs - Cache these directories
• cache: false - Don't cache dev server

Workspace Protocol

Use pnpm for best monorepo support:

pnpm-workspace.yaml:

packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

Install workspace dependencies:

{
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/utils": "workspace:*"
  }
}

Shared Configuration

Share ESLint config:

// tooling/eslint-config/index.js
module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
  ],
  // ... rules
};

Use in packages:

{
  "eslintConfig": {
    "extends": ["@repo/eslint-config"]
  }
}

Same pattern for TypeScript, Prettier, Jest configs.

CI/CD Optimization

Problem: CI runs all tests on every commit, even if code didn't change.

Solution: Turborepo's remote caching.

# Only rebuild what changed
turbo run build --filter=[HEAD^1]

# Use remote cache
turbo run build --cache-dir=.turbo/cache

GitHub Actions example:

name: CI

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'
      
      - run: pnpm install
      
      - name: Build
        run: pnpm turbo run build --filter=[HEAD^1]
      
      - name: Test
        run: pnpm turbo run test --filter=[HEAD^1]

Huge time savings on large PRs.

Versioning Strategy

For internal packages (not published to npm):

{
  "version": "0.0.0",
  "private": true
}

For published packages, use Changesets:

pnpm add -DW @changesets/cli
pnpm changeset init

Create changeset:

pnpm changeset

It asks:

• Which packages changed?
• Semver bump (major/minor/patch)?
• Changelog entry?

Then in CI:

pnpm changeset version
pnpm changeset publish

Automatic versioning and publishing.

Common Pitfalls

1. Not Using Task Dependencies

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"] // Build deps first!
    }
  }
}

Without this, apps might build before their dependencies.

2. Circular Dependencies

Never create circular dependencies:

❌ @repo/ui -> @repo/utils -> @repo/ui

Keep dependency graph acyclic.

3. Too Many Small Packages

Don't create a package for every util function. Group related code:

✅ @repo/utils (contains formatDate, parseUrl, etc.)
❌ @repo/format-date, @repo/parse-url, ...

4. Ignoring Cache Configuration

Configure outputs properly:

{
  "tasks": {
    "build": {
      "outputs": ["dist/**", "build/**", ".next/**"]
    }
  }
}

Missing this = no caching benefits.

Testing in Monorepo

Shared Jest config:

// packages/jest-config/jest.config.js
module.exports = {
  preset: "ts-jest",
  testEnvironment: "jsdom",
  moduleNameMapper: {
    "^@repo/(.*)$": "<rootDir>/../$1/src",
  },
};

Run all tests:

turbo run test

Run tests for specific package:

turbo run test --filter=@repo/ui

Development Workflow

Start all apps in dev mode:

turbo run dev --parallel

Work on specific app:

turbo run dev --filter=web

Watch mode for package:

turbo run dev --filter=@repo/ui

Migration Strategy

Moving to monorepo? Do it gradually:

1. Setup monorepo structure
2. Move shared code to packages
3. Migrate one app at a time
4. Update CI/CD incrementally
5. Train team on new workflows

Don't do big-bang migrations. Too risky.

Conclusion

Every time I set up a monorepo from scratch, I think about those six separate repos and the hours we spent chasing version mismatches across them. The initial monorepo setup takes effort — no question. But the alternative is worse: scattered code, broken dependency chains, and a CI pipeline that nobody fully understands.

Get the structure right. Invest in proper tooling. Cache aggressively. And keep your dependency graph clean. Future you will be grateful.

Questions about monorepos? Reach out.