Keep Frontend and Backend Always in Sync with OpenAPI and Orval

Keeping frontend and backend in sync is one of the most persistent sources of friction in modern web development. API contracts change, types drift, hooks become outdated, and suddenly half your UI breaks because someone renamed a field in the backend.

What if your API calls, TypeScript types (including enums), and data‑fetching hooks could stay automatically aligned with your backend — without boilerplate or manual updates?

That’s exactly where Orval shines. What Orval Supports

HTTP Clients

• Fetch
• Axios
• Custom base URL
• Custom HTTP client

Data Fetching

• React Query
• Vue Query
• Angular Query
• Solid Query
• Svelte Query
• SWR

Framework Integrations

• Angular (services)
• SolidStart (primitives)
• Hono (server templates)

Validation & Mocking

• Zod
• HTTP client + Zod schema
• MSW

##The Problem: Frontend–Backend Drift If you’ve worked on a real‑world product, you’ve likely experienced this:

• The backend changes an endpoint response shape.
• Frontend types become incorrect.
• API calls fail silently or cause runtime bugs.
• Hours are spent fixing mismatches instead of building features. Even with OpenAPI/Swagger documentation, many teams still:
• Manually write API clients
• Manually define TypeScript interfaces
• Manually create React Query (or similar) hooks This work is repetitive, time‑consuming, error‑prone, and guaranteed to fall out of sync.

About Orval

Orval is an OpenAPI code generator designed for modern TypeScript frontend stacks.

From a single OpenAPI specification, Orval can generate:

• Fully typed API clients
• TypeScript request/response models
• Data‑fetching integrations (React Query, Vue Query, and more)
• Mocking utilities In short, your OpenAPI spec becomes the single source of truth. No duplicated types. No outdated hooks. No guessing request shapes.

Why This Matters

1. Always in Sync with the Backend

Whenever the backend OpenAPI spec changes, simply run:

npx orval

Your API calls, types, and hooks update instantly — no refactoring, no missed fields, and no runtime surprises.

2. Massive Time Savings

Instead of writing:

• Axios or Fetch wrappers
• TypeScript interfaces
• Query hooks or middleware …you generate everything in seconds.

3. Safer Refactoring

Because everything is typed and generated from the contract:

Breaking backend changes fail at compile time Refactors become predictable Team confidence increases This is especially valuable for scaling teams.

Quick Start with Orval

1. Install

npm install orval — save-dev

2. Create an Orval Config (React Query example)

// orval.config.ts - Configuration file for Orval API client generator import { defineConfig } from 'orval' import { execSync } from 'child_process'

export default defineConfig({
  api: {
    // Input configuration: Source of the OpenAPI specification
    input: `${ENV.API_ENDPOINT}/v1/openapi.json`, // Fetches OpenAPI spec from the API endpoint

    output: {
      // Output configuration: Where and how to generate the API client
      target: './src/api/generated', // Directory where generated files will be placed
      client: 'react-query', // Generate React Query hooks for data fetching
      mode: 'tags-split', // Split API endpoints into separate files based on OpenAPI tags

      override: {
        // Custom configurations to override default behavior
        mutator: {
          // Custom HTTP client configuration
          path: './src/lib/axios.ts', // Path to the custom axios instance
          name: 'axiosMutator', // Name of the exported axios mutator function
        },
        query: {
          // React Query hook generation options
          useQuery: true, // Generate useQuery hooks for GET requests
          useInfinite: true, // Generate useInfiniteQuery hooks for paginated data
          useMutation: true, // Generate useMutation hooks for POST/PUT/DELETE requests
        },
      },
    },

    hooks: {
      // Post-generation hooks: Actions to run after files are generated
      afterAllFilesWrite: () => {
        // Automatically format the generated API files for consistent code style
        console.log('🎨 Formatting generated API files...')
        // Script should be defined on package.json
        execSync('npm run api:format', { stdio: 'inherit' }) // Run prettier/eslint formatting
        console.log('✅ API files formatted!')
      },
    },
  },
})
// package.json
// ...
"scripts": {
  // ...
    "api:generate": "orval",
    "api:auto-generate": "npx orval --watch", // this will watch for changes and regenerate
    "api:format": "prettier --write \"src/api/generated/**/*.ts\""
  },
// ...

3. Generate Your API Layer

npx orval

You now have:

• Typed API functions
• React Query hooks such as useGetUsers()
• Request and response types All synchronized with your backend.

Real‑World Workflow

A healthy team workflow with Orval looks like this:

• Backend updates the OpenAPI spec.
• Frontend pulls the latest spec.
• Run npx orval.
• TypeScript flags any breaking changes.
• Fix the UI confidently. No Slack messages asking for payload shapes. No guessing endpoints. No stale code.

Just contract‑driven development.

Bonus: Mocking for Faster UI Development

Orval can also generate mock handlers, allowing frontend teams to:

• Work before the backend is ready
• Build Storybook components with real types
• Run integration‑like tests locally This enables true parallel development without blockers.

When Should You Use Orval?

Orval is especially useful if:

• You use TypeScript
• Your backend exposes OpenAPI
• You rely on query libraries (React Query, Vue Query, etc.) or Axios
• Your team wants fewer runtime bugs and less boilerplate For small prototypes it may feel like overkill. For production applications, it’s a major productivity win.

Final Thoughts

Frontend–backend drift isn’t just a tooling issue — it’s a contract issue.

Orval solves this by turning your OpenAPI specification into living, typed frontend code that stays automatically synchronized.

The result:

• Less boilerplate
• Fewer bugs
• Faster development
• Happier developers If your team is still manually writing API calls and types in 2025, it might be time to let Orval handle the boring parts.

Have you tried Orval or another OpenAPI generator? I’d love to hear your experience.