/orval

name: orval
description: Generate type-safe API clients, TanStack Query/SWR hooks, Zod schemas, MSW mocks, Hono server handlers, MCP servers, and SolidStart actions from OpenAPI specs using Orval. Covers all clients (React/Vue/Svelte/Solid/Angular Query, Fetch, Axios), custom HTTP mutators, authentication patterns, NDJSON streaming, programmatic API, and advanced configuration.

Orval - OpenAPI to TypeScript Code Generator

Orval generates type-safe TypeScript clients, hooks, schemas, mocks, and server handlers from OpenAPI v3/Swagger v2 specifications.

Quick Start

Installation

npm install orval -D
# or yarn add orval -D
# or pnpm add orval -D
# or bun add orval -D

Minimal Configuration

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
    },
    output: {
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
    },
  },
});

Run

npx orval
npx orval --config ./orval.config.ts
npx orval --project petstore
npx orval --watch

Choosing Your Setup

Client Selection Guide

| Use Case | Client | httpClient | Notes | | ------------------------ | ----------------- | ------------------ | --------------------------------------- | | React with server state | `react-query` | `fetch` or `axios` | TanStack Query hooks | | Vue 3 with server state | `vue-query` | `fetch` or `axios` | TanStack Query for Vue | | Svelte with server state | `svelte-query` | `fetch` or `axios` | TanStack Query for Svelte | | SolidJS standalone app | `solid-query` | `fetch` or `axios` | TanStack Query for Solid | | SolidStart full-stack | `solid-start` | native fetch | Uses `query()`/`action()` primitives | | Angular with signals | `angular-query` | `angular` | Injectable functions, signal reactivity | | Angular traditional | `angular` | — | HttpClient services | | React with SWR | `swr` | `fetch` or `axios` | Vercel SWR hooks | | Lightweight / Edge | `fetch` | — | Zero dependencies, works everywhere | | Node.js / existing Axios | `axios-functions` | — | Factory functions (default) | | Axios with DI | `axios` | — | Injectable Axios instance | | Validation only | `zod` | — | Zod schemas, no HTTP client | | Backend API server | `hono` | — | Hono handlers with Zod validation | | AI agent tools | `mcp` | — | Model Context Protocol servers |

Mode Selection Guide

• **`single`** — Everything in one file. Best for small APIs.
• **`split`** — Separate files: `petstore.ts`, `petstore.schemas.ts`, `petstore.msw.ts`. Good for medium APIs.
• **`tags`** — One file per OpenAPI tag + shared schemas. Organizes by domain.
• **`tags-split`** — Folder per tag with split files. Best for large APIs. Recommended.

httpClient Option

For `react-query`, `vue-query`, `svelte-query`, and `swr` clients:

output: {
  client: 'react-query',
  httpClient: 'fetch',  // 'fetch' (default) | 'axios'
}

For `angular-query`:

output: {
  client: 'angular-query',
  httpClient: 'angular',  // Uses Angular HttpClient
}

Configuration Reference

Config Structure

import { defineConfig } from 'orval';

export default defineConfig({
  [projectName]: {
    input: InputOptions,
    output: OutputOptions,
    hooks: HooksOptions,
  },
});

Multiple projects can share the same config file with different input/output settings.

Input Options

input: {
  target: './spec.yaml',              // Path or URL to OpenAPI spec (required)
  override: {
    transformer: './transform.js',    // Transform spec before generation
  },
  filters: {
    mode: 'include',                  // 'include' | 'exclude'
    tags: ['pets', /health/],         // Filter by OpenAPI tags
    schemas: ['Pet', /Error/],        // Filter by schema names
  },
  parserOptions: {
    headers: [                        // Auth headers for remote spec URLs
      {
        domains: ['api.example.com'],
        headers: {
          Authorization: 'Bearer YOUR_TOKEN',
          'X-API-Key': 'your-api-key',
        },
      },
    ],
  },
}

Output Options

output: {
  target: './src/api/endpoints.ts',     // Output path (required)
  client: 'react-query',               // Client type (see table above)
  httpClient: 'fetch',                  // 'fetch' (default) | 'axios' | 'angular'
  mode: 'tags-split',                   // 'single' | 'split' | 'tags' | 'tags-split'
  schemas: './src/api/model',           // Output path for model types
  operationSchemas: './src/api/params', // Separate path for operation-derived types
  workspace: 'src/',                    // Base folder for all files
  fileExtension: '.ts',                 // Custom file extension
  namingConvention: 'camelCase',        // File naming: camelCase | PascalCase | snake_case | kebab-case
  indexFiles: true,                     // Generate index.ts barrel files
  clean: true,                          // Clean output before generating
  prettier: true,                       // Format with Prettier
  biome: true,                          // Format with Biome
  headers: true,                        // Generate header parameters
  baseUrl: '/api/v2',                   // API base URL
  // or from spec:
  // baseUrl: { getBaseUrlFromSpecification: true, index: 0, variables: { environment: 'api.dev' } },
  mocks: true,                          // Generate MSW + Fa