harshitsinghbhandari Frontend Architecture
Overview
Opinionated, blessed-default guidance for architecting the frontend of a web app you intend to scale. The bet: a handful of decisions made correctly on day 1 cost almost nothing up front and save a future engineer from tedious, low-value rework later. You don't have to learn each tool deeply (you direct agents to apply these defaults), but the decisions still have to be made deliberately.
Core principle: Pick the blessed default below unless the user has a specific reason to deviate. These are not a menu of equal options; they are recommendations with a track record. State the pick, apply it, and only surface alternatives when the project's constraints genuinely break the default.
When to Use
- Scaffolding a new React web app from scratch.
- Any structural decision mid-project: data fetching, routing, state, styling, real-time transport, deploy target, type generation, query-param state.
- The user asks "how should we do X" where X is a frontend architecture concern.
- Reviewing or correcting an existing frontend's architecture.
When NOT to use:
- Single-component or single-bug work that doesn't touch architecture.
- Non-React stacks (the specific tool picks here assume React; the principles still transfer, but flag that the picks are React-centric).
- Backend-only or infra-only tasks.
The Blessed Stack (Quick Reference)
| Decision | Blessed default | One-line why |
|---|---|---|
| Backend types | Generate a client from an OpenAPI spec | Hand-typing backend types is banned. The spec is the source of truth. |
| Server state / data fetching | TanStack Query | Caching, invalidation, and async state, solved. Other libs look similar but this one is the standard. |
| Routing | TanStack Router, or React Router framework mode | Type-safe routes + data loaders beat hand-rolled route trees. |
| Route data | Route data loaders | Load in the route, not in component effects. |
| Query-param state | nuqs (or TanStack), type-safe | If state lives in the URL, make it a first-class, typed citizen. |
| Server state mgmt | TanStack Query (one solution, that's it) | Most apps need exactly one server-state layer and nothing more. |
| Bespoke client state | Zustand | Simple, unopinionated, scales for the rare local-state need. |
| Heavy interactive state | XState / xstate-store | Model the frontend as a state machine to escape useEffect hell. |
| Memoization | React Compiler (drop manual useMemo/useCallback) | The compiler handles it. Update your priors. |
| Loading / error UI | Suspense + ErrorBoundary | isPending/isError sprinkled everywhere is madness. |
| Real-time transport | One blessed WebSocket/SSE path, chosen day 1 | Especially for anything AI. Decide the pattern before you need it. |
| Styling | A design system / component library, not raw Tailwind sprawl | Tailwind is fun but hard to keep consistent at scale; you want an "agent-first" component layer. |
| Deploy | Cloudflare or Vercel | Other hosts have weird missing features. |
| SPA + Next.js | Don't | A pure SPA on Next.js makes no sense. |
The Decisions In Detail
1. Generate types from the backend, never hand-type them
Make the server emit an OpenAPI spec, then codegen all client-side types and request code from it. Typing backend types by hand should be treated as banned: it drifts, it rots, and it produces subtle bugs at the boundary. The generated client is the contract.
2. Decide how the client talks to the backend, deliberately
For REST or GraphQL, use TanStack Query. It is the goated default for server-state: caching, background refetch, invalidation, and request dedup come for free. Competing libraries look superficially similar; pick TanStack Query unless there's a concrete reason not to.
3. If you want sync or offline, architect it on day 1
Linear-style local-first sync and offline mode are brutal to bolt on later. If the product needs them, design for them from the very first commit. This is the single decision most likely to force a painful rewrite if deferred. Think about it HARD before scaffolding.
4. Routing: modern router + data loaders
Plain React Router still works, but the ecosystem has moved on. Use TanStack Router or React Router's framework mode, and lean on route data loaders so data fetching is declared at the route, not buried in component effects.
5. Query-param state is real state, so make it typed
If you keep meaningful state in query params (filters, tabs, selections), treat it as a first-class, type-safe citizen with nuqs or TanStack. Stringly-typed URL parsing scattered through components is a maintenance trap.
6. One server-state solution; reach for more only when needed
Most apps need a single server-state layer (TanStack Query) and nothing else. For genuine bespoke local needs, Zustand is the clean default. For a highly interactive app (lots of transient UI state, media playing, things entering and leaving view) lock in and model it as a state machine with XState. Trust the state-machine framing here; it is how you keep sanity and stay out of useEffect hell.
7. React Compiler changes your defaults
The React Compiler is here. Stop reflexively wrapping things in useMemo/useCallback. Write straightforward code and let the compiler memoize. Update your priors accordingly.
8. Loading and error states: Suspense + ErrorBoundary
Threading isPending and isError through every component is madness. Lean into Suspense for loading and ErrorBoundary for failures so the UI states are structural, not manually plumbed.
9. Pick a blessed real-time path early
For anything AI-related (and most live apps), choose one canonical pattern for WebSockets and SSE on day 1 and route everything through it. Deciding this once, early, pays dividends; discovering you have three ad-hoc socket patterns later does not.
10. Styling: a design system, not Tailwind sprawl
Tailwind is easy and fun but makes consistent styling hard to maintain across a large app. Invest in a design system / component library (an "agent-first" component layer that agents can compose predictably) rather than scattering utility classes everywhere.
11. Bend the router to the product
Don't be afraid to hack your routing library to fit the product. Drawers showing extra info are everywhere; you should be able to say "here's a route, render it as a drawer" and have everything handled from there. The router serves the UX, not the other way around.
12. Deploy and framework choices
Deploy on Cloudflare or Vercel; other services tend to have weird missing features. And if you're building a pure SPA, do not use Next.js; it adds machinery that buys you nothing for that shape of app.
The Meta-Principle: Build the Factory
Once you've built something people want, the next job is to build the factory that builds the thing efficiently. Every decision above is partly in service of that: generated types, typed routes, a real design system, and a state model an agent can reason about all make the codebase a place where agents (and humans) ship fast and safely. Architect for the factory, not just the first feature.
Common Mistakes
- Hand-typing backend types "to move fast." It is slower within a week. Generate from the spec.
- Deferring sync/offline until users ask. By then it's a rewrite. Decide on day 1.
- Sprinkling
isPending/isErrorinstead of using Suspense + ErrorBoundary. - Reaching for Redux/extra state libs when TanStack Query already covers server state.
- Reflexive
useMemo/useCallbackafter React Compiler exists. - Raw Tailwind everywhere with no component layer, then fighting inconsistency at scale.
- Next.js for a pure SPA, inheriting SSR machinery you never use.
- Ad-hoc WebSocket/SSE code per feature instead of one blessed transport.
How To Apply
When this skill fires, don't dump the whole table. Identify which decision(s) the task touches, state the blessed default for those, apply it, and note the "why" in one line. Only present alternatives if the project's constraints actually break the default (e.g. a non-React stack, a hard requirement the default can't meet). Keep the opinions: these are recommendations with a track record, not a neutral survey.