modern-frontend-architecture

name

modern-frontend-architecture

description

Use when starting, scaffolding, or reviewing the architecture of a web frontend, or making any frontend architecture decision — framework/stack choice, client-server data, state management, routing/URL state, styling and design systems, i18n/RTL, server-side logging/observability, or deploy target. Triggers on new web-app setup, "which library/framework should I use", data fetching and mutations, global vs local state, component and design-system design, internationalization, and Cloudflare/self-host/Vercel deploy questions.

Modern Frontend Architecture

House standard for web frontends. Take the Use default; open the reference for how + why.

Guiding rule: establish the boundary on day 1, defer the implementation. Default to the collection seam — don't build Electric. Pick the realtime transport — don't build the system.

Current best, not eternal truth — last reviewed 2026-08-24. The boundaries (the decisions and seams) below are durable; the named tools and versions filling them are the current best as of that review. If today's date is well past it, treat specific tool/version picks as possibly superseded — keep the decision, re-verify what best fills it now. This is the guiding rule applied to the skill itself: the seam is the commitment, the tool is the implementation.

Defer, don't duplicate: platform HTML/CSS/JS → modern-web-guidance · composition → vercel-composition-patterns · React perf → vercel-react-best-practices · motion → web-animation-design. The two vercel-* are companion skills — install them alongside this one (see README); if a target project doesn't have them, fall back to modern-web-guidance + first principles, don't inline their depth here.

Reference implementation: ultimate-ts-starter (github.com/Amir-Abushanab/ultimate-ts-starter) — copy patterns from it.

Defaults

Decision	Use	Not	Why (when non-obvious)
Package manager	pnpm + catalogs · existing Bun toolchain: keep Bun, mirror the gates (bunfig minimumReleaseAge = 604800)	npm / yarn · Bun without the cooldown configured	pnpm takes precedence on greenfield; Bun ≥ 1.3 has the same enforced install gate (seconds, not pnpm's minutes)
Web stack	TanStack Start (default; SSR+SSG) · Astro only if super-SEO-critical or content-only	Next.js · Astro/split by default	one Start app covers mixed sites; reach for Astro only when SEO is paramount; Next couples rendering to its model + Vercel
Deploy	Cloudflare · self-host (first-class)	Vercel
Lint / format	oxc (oxlint + oxfmt), error-only	ESLint+Prettier · Biome	Rust-fast and skips the TS compiler API, so TS 7 works today
Types	TS 7 native tsc, strict + noUncheckedIndexedAccess	TS 6 · loose
Wire types	oRPC + zod · simple Hono-server projects: Hono RPC (hc<AppType>)	tRPC · hand-typed	OpenAPI-compatible, edge-agnostic; Hono RPC = same seam, no extra layer — graduate to oRPC at OpenAPI / non-TS consumers
Server data	oRPC → TanStack Query → TanStack DB collection (useLiveQuery, optimistic)	raw Query for entity data · hand-rolled cache writes	collection gives optimistic+rollback and the sync seam free — deletes ~80 lines
Loading / error	Suspense + ErrorBoundary	isPending / isError plumbing
Memoization	React Compiler via oxc — react({ compiler: true }) + oxc-transform-react	manual useMemo / useCallback · babel-plugin-react-compiler (fallback only)	one Rust pass (compiler + JSX + Fast Refresh), ~10× faster, toolchain stays Babel-free
Client state	collection → zustand / xstate-store → XState	Context/useEffect webs · a hand-rolled FSM that keeps growing

References

For…	Read
stack · deploy · toolchain · repo skeleton	references/stack-selection.md
data · URL state · realtime	references/data-and-typesafety.md
where state lives	references/state.md
components · design system	references/design-system.md
internationalization	references/i18n-rtl.md
CI gates · git hooks · supply-chain · enforcement · the factory	references/agent-first-factory.md
rule → enforcer map · ratchets	references/enforcement-map.md
runtime security · CSP · headers · secrets · CSRF · XSS	references/security.md
server-side logging · wide events · client telemetry · sampling	references/logging.md

Brownfield & hard constraints

These are day-1 greenfield defaults. On an existing codebase, or when a real constraint (client mandate, an existing Next/Vercel app, the team's skill set) rules out the house choice:

• Adopt the seam, not necessarily the tool. The durable value is the boundaries — typed wire boundary, the collection/store seam, one realtime transport, token-only components. Most are portable onto another stack; take the seam even where the tool differs.
• Non-conformance isn't a reason to migrate. A rewrite is justified by a concrete cost the current choice imposes, not by "it's not the table." Match the default on new surfaces; migrate an existing one only when it's already being changed for another reason (strangler, not big-bang).
• The "Never"s are day-1 defaults, not migration mandates. Already on Next.js/Vercel and it works? Don't rip it out — adopt the portable seams now, reach for the house stack at the next greenfield boundary (new app, major rewrite). Migration specifics → references/stack-selection.md.