OrvalSAFE

orval is able to generate client with appropriate type-signatures (TypeScript) from any valid OpenAPI v3 or Swagger v2 specification, either in yaml or json formats. 🍺

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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

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

### Minimal Configuration

```ts
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

```bash
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:

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

For `angular-query`:

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

## Configuration Reference

### Config Structure

```ts
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

```ts
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

```ts
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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Orval](https://modelsatlas.com/skills/orval-labs/orval/badge.svg)](https://modelsatlas.com/skills/orval-labs/orval/)

Not your listing, or something out of date? Claim or update your listing.