Enforce typed network boundaries in React frontends

A portable, framework-agnostic frontend skill establishing type safety at the network edge of any React or React Native app - a companion to the frontend-architecture skill (the client lives in shared/api-client/) and the foundation frontend-optimistic-mutations builds on. Five core ideas: one typed apiClient is the only fetch boundary, so components and hooks never call fetch/axios directly (enforced via ESLint no-restricted-imports); parse-don't-validate turns wire JSON into trusted domain types at that one boundary via a schema library (Zod, Valibot, ArkType, or io-ts - the rule, not the library, is fixed), so downstream code never writes defensive ?. chains; one response envelope ({ data } on success, { error } on failure) is unwrapped once inside the client, so callers get a typed payload or a throw, never a raw envelope; one normalized ApiError type collapses every failure mode (server error envelope, non-2xx status, malformed body, network failure, abort) into a single shape carrying a machine code, HTTP status, optional per-field errors, and a stable i18n messageKey - never the raw server message shown to users; and domain identifiers are branded nominal types (InvoiceId, CustomerId) so the compiler rejects passing one ID type where another is expected, at zero runtime cost since brands erase at compile time. Side effects (toasts, redirects) live in the query layer's onError, not in the client itself, and per-field server errors map directly onto form-field errors. A library-adapter table shows where the client is called and where ApiError is handled across TanStack Query (queryFn/mutationFn plus onError), RTK Query (baseQuery wrapping the client plus transformErrorResponse), SWR (a fetcher function plus onError in SWRConfig), and plain fetch hooks for React Native, which needs the same client unchanged aside from possibly swapping cookie credentials for a token header depending on auth. A conventions checklist enforces all of this in review: one apiClient with no fetch/axios elsewhere, a framework-free client, boundary-only parsing, one envelope, one ApiError shape, branded IDs, and i18n-resolved error messages.

Use it when establishing or auditing the network boundary of a React or React Native app - the single API client, response parsing, error normalization, and ID typing. It is a discipline at the network edge, not a state library or styling system.

Given a backend endpoint and its response shape, it produces a typed client call, a schema-parsed domain type, and either the unwrapped data or a thrown ApiError with a code, status, and optional field errors - never an untyped or partially-validated value reaching a component.

export const invoiceSchema = z.object({ id: z.string().transform(toInvoiceId), /* ... */ });

Pairs with any schema library (Zod, Valibot, ArkType, io-ts) for parsing and any data-fetching layer (TanStack Query, RTK Query, SWR, or plain fetch hooks) for calling the client and handling ApiError.

Frontend teams who want a single, enforceable typed boundary between the network and the app - no ad-hoc fetch calls, no untyped API responses drifting silently into components, and one consistent error shape to handle everywhere instead of catching a different failure mode per call site.