How to Build an API-First Front End with OpenAPI, Orval, TanStack Query, Zod

How to Build an API-First Frontend with OpenAPI, Orval, TanStack Query, Zod, and Next.js

The React Systems Newsletter

SubscribeSign in

How to Build an API-First Frontend with OpenAPI, Orval, TanStack Query, Zod, and Next.js

The React Systems Newsletter May 27, 2026

Frontend development has a repetitive problem that almost every team eventually rediscovers. You receive an API endpoint. Thanks for reading! Subscribe for free to receive new posts and support my work.

You write: request functions

response types

React hooks

loading states

mutation handlers

mocks

validation logic

Then the backend changes one field. Now: generated screenshots fail

UI forms break

stale interfaces lie to TypeScript

QA opens twelve tickets

The larger the application becomes, the worse this cycle gets. The irony is that modern teams already possess something capable of solving a large part of this problem: the API contract. That contract usually exists as an OpenAPI specification. Unfortunately, many teams still treat OpenAPI as documentation. Useful documentation. Ignored documentation. Static documentation. But OpenAPI can be much more than a Swagger page living somewhere inside infrastructure documentation. In a modern TypeScript workflow, OpenAPI can become the single source of truth powering your entire frontend integration layer. Why API-First Development Actually Matters

Many frontend teams still work in a backend-last model. The workflow usually looks like this: UI design begins.

Backend implementation begins.

Frontend waits.

Backend finishes endpoints.

Frontend starts integration.

Everybody discovers mismatched assumptions.

You have probably lived through this already. Examples: Backend: "full_name": "Jane Doe" }Frontend expected: fullName: string }Backend: "status": "pending_review" }Frontend enum: type Status = "draft" | "published";Runtime chaos follows. API-First changes the order. Instead of backend implementation being the first deliverable, the API contract becomes the first deliverable . That means frontend developers can begin work before the backend exists. Not with fake hand-written mocks. Not with guessed interfaces. With a real contract.

OpenAPI as a Development Asset — Not Documentation

An OpenAPI specification can drive far more than Swagger UI. A modern workflow can automatically generate: TypeScript models

API clients

React hooks

query utilities

mocks

validation schemas

documentation

testing helpers

The important shift is conceptual. Treat OpenAPI like source code. Version it. Review it. Diff it. Generate from it. Your repository structure might look like this: my-app/ ├── openapi/ │ └── schema.yaml ├── src/ │ ├── api/ │ ├── components/ │ ├── hooks/ │ └── app/ ├── orval.config.ts └── package.jsonKeeping specs inside Git matters. You gain: version history

review visibility

contract diffs

CI automation

team synchronization

Frontend engineers no longer rely on outdated screenshots of Swagger pages.

Generating a Typed Client with Orval

Instead of manually writing fetch wrappers, we will use Orval . Install dependencies: pnpm add -D orvalCreate configuration. orval.config.ts import { defineConfig } from "orval";

export default defineConfig({ catalogApi: { input: { target: "./openapi/schema.yaml" },

output: { target: "./src/api/generated.ts",

client: "react-query",

mode: "single" });Now add a script. "scripts": { "api:generate": "orval" }Run generation. pnpm api:generateOrval now generates: request functions

types

TanStack Query hooks

mutation helpers

No manual API boilerplate.

Building a Real Query Layer with TanStack Query

Generated clients become significantly more useful once combined with TanStack Query. Install: pnpm add @tanstack/react-queryCreate provider setup. providers/query-provider.tsx "use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function AppProviders({ children }: React.PropsWithChildren) {

return (

{children}

); }Now generated hooks become extremely clean. const { data, isLoading, error } = useGetProducts();No handwritten hooks. No duplicated loading logic. No copy-pasted fetch abstractions.

Type Safety Is Useful — But Runtime Validation Still Matters

This is where many TypeScript projects become overconfident. Generated interfaces help. They do not validate runtime payloads. Your server can still return: "price": "broken" }while TypeScript confidently believes: price: numberThis is where Zod enters the workflow. Install: pnpm add zodDefine schemas. import { z } from "zod";

export const ProductSchema = z.object({ id: z.number(), title: z.string(), price: z.number() });Runtime validation: const result = ProductSchema.parse( response.data );Now bad payloads fail loudly. Not silently. API-First becomes stronger when combined with runtime guarantees.

Starting Frontend Development Before Backend Exists

One of the most valuable parts of...

How to Build an API-First Front End with OpenAPI, Orval, TanStack Query, Zod

Related Articles

Amazon, Facebook, FBI have access to a private intelligence-sharing network

Agent Memory: An Anatomy

SpaceX not the behemoth everyone thought

The Mirror Is Part of the Machine

Elevated error rates on requests to multiple models