orval-labs/orval

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

Summary

Orval is a TypeScript code generator that produces type-safe client code, models, request functions, and data-fetching hooks from an OpenAPI v3 or Swagger v2 specification (in YAML or JSON). It targets a wide range of frontend frameworks and data-fetching libraries, so the same API spec can drive clients in React, Angular, Vue, Svelte, Solid, and Hono projects. It also generates MSW-based mocks for local development and testing.

What it is useful for

Orval is useful when a team wants to stop hand-writing API client code and keep TypeScript types in lockstep with a backend's OpenAPI spec. A few concrete scenarios it supports out of the box:

• Generating React Query, SWR, Vue Query, Pinia Colada, Svelte Query, Solid Query, or Angular Query hooks directly from the spec.
• Producing schemas for zod or Effect so request and response payloads can be validated at runtime.
• Generating native fetch-based clients for frameworks like Next.js or Hono where an extra HTTP library is unwanted.
• Generating MSW mock handlers and faker-backed data for local development, storybook, and unit tests.
• Producing an MCP server definition from an existing spec.

The README notes a breaking-change history at version 8.0.0+, so projects upgrading from older major versions should consult the migration guide.

How engineers can use it

1. Decide the runtime. The README states Orval 8+ requires Node.js 22.18 or newer. On older Node LTS releases, the README recommends running generation through the official Docker image.
2. Run Orval against your spec. The documented basic Docker invocation is:

   docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
   

   For a local API, the docs show mapping localhost to host.docker.internal and setting ORVAL_SWAGGER_URL, for example:

   docker run --rm -v "$(pwd):/app" -w /app \
     -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
     -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
     ghcr.io/orval-labs/orval --config ./orval.config.ts
   

3. Point Orval at a config. The examples above use --config ./orval.config.ts, which is the supported way to choose the target client (React Query, Angular, Hono, etc.) and output paths.
4. Inspect the output. The repository ships a samples/ directory with working examples for each supported target (react-query, vue-query, svelte-query, pinia-colada, solid-query, solid-start, react-app-with-swr, angular-app, hono, next-app-with-fetch, mcp), so engineers can compare their config against a known-good reference.
5. Try a spec quickly. The README points to a hosted Playground at orval.dev/playground for ad-hoc experimentation without local setup.

Exact configuration options (output targets, mock strategies, custom mutators) are not fully reproduced in the README excerpt; the README directs readers to the full documentation site for those details.