> *Estimated reading time: 15-20 minutes.* We went from fighting the DOM with jQuery to managing complex global states with Redux, then simplified everything with React Query (TanStack Query) to handle server state on the client. Today, with the arrival of **Next.js 16** and **React 19**, we are facing a new paradigm shift: the return to the server and the radical simplification of architecture. In this article, we will break down how to build a robust, minimalist, and maintainable application under a **Hexagonal Architecture**, eliminating dependencies we thought were essential (like React Query) and establishing a "single source of truth" through strict types with Zod. We will base this analysis on a common practical case: a **Real Estate Platform**, where managing filters, multi-step forms, and complex data is critical. --- ## 1. The New Game Board: Minimalist Hexagonal Architecture Before talking about tools, let's talk about structure. The biggest mistake in frontend projects is mixing *what the application does* (Business Rules) with *how it looks* (UI/React). To solve this, we adopt a strict variation of **Ports and Adapters**: ### 📂 `domain/` (The Immutable Truth) Here lives pure business logic. **It is forbidden to import React, Next.js, or third-party libraries.** - **Entities:** Pure TypeScript types (`type Property`, `type Agent`). - **Repositories (Ports):** Interfaces that define contracts (`IPropertyRepository`). *If tomorrow you change Next.js for Remix or Vue, this folder remains untouched.* ### 📂 `application/` (The Orchestration) Contains the **Use Cases**. - Classes or functions that execute a specific action: `CreatePropertyListingUseCase`, `GetPropertyBySlugUseCase`. - Business validation is applied here, and repositories are called. ### 📂 `infrastructure/` (The Dirty Details) Here is where the framework shines. It is the only layer that "knows" we are using Next.js. - **UI:** Components, Hooks, Stores. - **Implementations:** Data fetching, DB adapters (Supabase, Firebase). ### 📂 `shared/` (The Glue) Cross-cutting utilities. - **Schemas:** **Zod** lives here. It is crucial that schemas are here to be consumed by both the `domain` (to infer types) and the `infrastructure` (to validate forms and APIs). --- ## 2. Why You No Longer Need React Query in Next.js App Router For years, `react-query` was our Swiss Army knife to solve the problem of: *"How do I fetch data, cache it, handle loading, and revalidate?"*. With **Next.js App Router** and **React Server Components (RSC)**, the framework has absorbed these responsibilities. ### The Problem of Excessive "Client-Side Fetching" In the old pattern ("Pages Router" or SPA): 1. The component mounts. 2. `useEffect` triggers a fetch. 3. We show a spinner. 4. Data arrives -> We render. This caused **waterfalls** (cascades of requests) and forced us to have a complex cache manager on the client. ### The Native Solution: Fetch + RSC In our architecture, the UI component (Infrastructure) does not fetch. The component is a **Server Component** that directly calls the Use Case, which calls the Repository. **Example of Repository in Infrastructure (`infrastructure/api/property-repository.impl.ts`):** ```typescript // Note: We use the native fetch extended by Next.js export class ApiPropertyRepository implements IPropertyRepository { async getPropertyBySlug(slug: string): Promise { const res = await fetch(`${process.env.API_URL}/properties/${slug}`, { // 1. Automatic Caching: Defaults to 'force-cache' if not dynamic. // 2. Time-based Revalidation (ISR) or On-Demand (Tags). next: { tags: [`property-${slug}`], revalidate: 3600 // 1 hour } }); if (!res.ok) return null; // We validate that what comes from the backend is what we expect (See Zod section below) const data = await res.json(); return propertySchema.parse(data); } } ``` ### How Do We Replace React Query Features? 1. **Caching and Deduplication:** Next.js performs "Request Memoization". If you call `getPropertyBySlug` in the Layout and then in the Page, only one real fetch is executed. 2. **Revalidation (Invalidate Queries):** Instead of `queryClient.invalidateQueries`, we use **Server Actions** with `revalidateTag` or `revalidatePath`. 3. **Loading States:** We use `Suspense` and `loading.tsx` from Next.js. The UI is declarative, not managed by `isLoading` booleans. **Conclusion:** For read operations (GET) in Server Components, **React Query is redundant**. It unnecessarily adds weight to the JS bundle. Reserve it only for complex client interactions (real-time polling, purely client-side infinite scroll). --- ## 3. Global State vs. URL State: The Store Trap Another common pattern we must correct is the abuse of Global Stores (Zustand, Redux, Context). **The Myth:** *"I need to put the current form step in a global state so my components know where they are."* **The Reality:** Global state is volatile. If the user reloads the page, where does their progress go? If they share the link, does their friend see the same thing? ### The Golden Rule of State Before creating a `useStore`, ask yourself: 1. **Should it be shareable?** -> **URL (`searchParams`)**. 2. **Does it come from the server?** -> **Server Component Data**. 3. **Is it ephemeral to a component?** -> **`useState` / `useReducer`**. 4. **Is it form state (Loading/Error)?** -> **`useActionState` (React 19)**. 5. **Is it global session configuration?** -> **Global Store**. ### Form Management: Goodbye Global Store with `useActionState` A classic anti-pattern is storing validation errors or form `isLoading` state in a global Store or complex manual states. React 19 introduces `useActionState`, designed specifically to manage the result of Server Actions. This hook encapsulates the interaction lifecycle (submit -> server validation -> response), keeping the state localized and clean. ```tsx // infrastructure/ui/create-listing-form.tsx const [state, formAction, isPending] = useActionState(createListingUseCase, initialState); // `state` contains errors returned by the domain (Zod) // `isPending` is managed automatically during Server Action execution ``` ### Case Study: The Publishing Wizard In a real estate app, publishing a house requires several steps: (Details -> Location -> Photos). Instead of a Store, we use the URL. **Bad Pattern (Store):** ```typescript // infrastructure/store/listing-store.ts // ❌ If I reload, I go back to step 1. I can't share the link to step 3. const useListingStore = create((set) => ({ step: 1, setStep: (step) => set({ step }) })); ``` **Senior Pattern (URL Driven State):** ```tsx // infrastructure/ui/property/listing-flow.tsx import { useSearchParams, useRouter } from 'next/navigation'; export const PropertyListingFlow = () => { const searchParams = useSearchParams(); const step = searchParams.get('step') ?? 'details'; // 'details' | 'location' | 'photos' const navigateTo = (newStep: string) => { // ✅ We update the URL. The browser manages history. // ✅ When sharing the link, the receiver arrives at the same point. router.push(`?step=${newStep}`, { scroll: false }); }; return ( <> {step === 'details' && navigateTo('location')} />} {step === 'location' && } ); }; ``` This drastically reduces the amount of JS code we need to maintain and synchronize. **The URL is the most robust Store that exists.** --- ## 4. Zod: Defensive Typing and "Schema-First" TypeScript gives us compile-time safety, but **Zod gives us runtime safety**. In a professional architecture, we don't blindly trust that the Backend fulfills its contract. ### The "Schema-First" Pattern Instead of writing TS interfaces manually, we write Zod schemas in `shared/schemas` and derive the types. ```typescript // shared/schemas/property.ts import { z } from "zod"; export const propertySchema = z.object({ id: z.string().uuid(), title: z.string().min(10), price: z.number().positive(), // On-the-fly data transformation: ISO string -> Date Object listedAt: z.string().transform((str) => new Date(str)), isAvailable: z.boolean().default(true) }); // ✨ Magic: A single source of truth export type Property = z.infer; ``` ### Response Parsing It is common to type the axios/fetch response with `as Property`. **This is a lie.** You are forcing the compiler to believe something you haven't checked. **Incorrect Way (Blind Faith):** ```typescript const data = await res.json() as Property; // 🚩 High risk if API changes ``` **Senior Way (Defensive Parsing):** In our infrastructure layer, we use `safeParse`. If the backend changes a field name, our application explodes controllably in the adaptation layer with a clear message, instead of silently rendering `undefined` in the UI. ```typescript // infrastructure/api/property-repository.ts const json = await res.json(); const result = propertySchema.safeParse(json); if (!result.success) { console.error("Critical: API Contract Breach", result.error); throw new Error("Data integrity error"); } return result.data; // Here TypeScript knows it's 100% a valid Property ``` ### Reuse in Forms The same `createPropertySchema` you use to validate the `POST` in your API Route (Backend), you import into your client component with `react-hook-form` and `zodResolver`. **Result:** Validation logic written ONCE, executed on client (immediate UX) and server (security). --- ## 5. Performance: Does Excess Global State Affect It? Absolutely. Indiscriminate use of Context API or poorly designed global Stores causes the dreaded **"Render Drilling"**. A change in a minor property of the Store can cause re-renders in components that don't even use that property if selectors aren't used properly. **Optimization Rule:** 1. **State Colocation:** Move state as low as possible in the component tree. 2. **Composition:** Use `children` to avoid prop drilling without needing Context. 3. **Server Components:** Move all data fetching logic to the server. A Server Component does not "re-render" on the client, it simply sends new HTML/RSC Payload. This eliminates much of the React performance burden in the browser. --- ## 6. React 19: The Final Cleanup If hexagonal architecture cleans our logic, **React 19** cleans our syntax. The new primitives eliminate much of the technical "glue" we used to write in the Infrastructure layer. ### The End of `useMemo` and `useCallback`: React Compiler Until now, optimizing React required filling the code with manual dependencies `[a, b]` and wrapping functions. If you forgot a dependency, a bug was guaranteed. With **React Compiler** (already available in Next.js 16), this is over. The compiler analyzes your code and automatically memorizes values and functions. * **Before:** `const handeClick = useCallback(() => { ... }, [dependency])` * **Now:** `const handleClick = () => { ... }` The code becomes optimization-agnostic. You write normal JavaScript, and React ensures it's fast. ### The `use` Hook: Goodbye `useEffect` for Data Remember having to declare a `loading` state, then a `useEffect`, do the fetch, set the data...? The new `use` hook allows consuming Promises directly in render (integrating with Suspense) and reading Contexts conditionally. ```tsx // infrastructure/ui/property-list.tsx import { use } from 'react'; export function PropertyList({ propertyPromise }: { propertyPromise: Promise }) { // 🤯 Suspends automatically until it resolves. // Goodbye isLoading, goodbye useEffect. const properties = use(propertyPromise); return

{p.title} - {p.price}€

; } ``` ### Painless Optimistic UX: `useOptimistic` Implementing optimistic updates (UI changes before the server responds) used to require complex rollback logic and manual caching. React 19 gives us `useOptimistic`. Ideal for instant interactions like marking a property as "Favorite": ```tsx // infrastructure/ui/property/favorite-button.tsx import { useOptimistic } from 'react'; export function FavoriteButton({ isFavorite, onToggle }: { isFavorite: boolean, onToggle: () => void }) { const [optimisticFavorite, toggleOptimistic] = useOptimistic( isFavorite, (state) => !state // Immediate visual logic ); return ( ); } ``` --- ## Conclusion Developing Senior-level software doesn't mean using the most complex libraries, but **knowing when NOT to use them**. By adopting this hexagonal architecture in Next.js: 1. We eliminate **React Query** in favor of native `fetch` and Server Actions. 2. We eliminate **Unnecessary Stores** in favor of the URL (`searchParams`). 3. We eliminate **Duplicated Interfaces** in favor of inference with Zod. 4. We gain a structure where the domain is sacred and the UI is just an implementation detail. Next time you start a project, don't start by installing dependencies. Start by designing your **Domain** and your **Schemas**. The rest is just carpentry.