orval

library0.0.9jsnpmunverified

Orval is a robust TypeScript client generator for OpenAPI/Swagger specifications, designed to automate the creation of type-safe API clients. It supports generating clients with various data fetching libraries, including React Query, Svelte Query, Axios, and Fetch, and can also generate mock data using Faker.js. The current stable version is 8.8.0, with minor and patch releases occurring frequently to incorporate new features (like `useSetQueryData` helpers), address bugs, and maintain compatibility with evolving ecosystem standards. Orval distinguishes itself through extensive customization options via its configuration file, allowing developers to precisely tailor the generated output for specific frameworks and architectural patterns, and by deeply integrating with OpenAPI schema validation and TypeScript type checking workflows to ensure high-quality, maintainable code.

http-networking web-framework serialization testing

npm install orval

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ORVAL

orval

http-networkingjavascriptv0.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'orval';

✗ const defineConfig = require('orval').defineConfig;

Primarily used in `orval.config.ts` for type-safe configuration. Orval is primarily an ESM package.

OrvalConfig

✓ import type { OrvalConfig } from 'orval';

Used for type hinting the configuration object when not using `defineConfig` directly or for extending configurations.

HooksOptions

✓ import type { HooksOptions } from 'orval';

Type definition for configuring lifecycle hooks within the Orval configuration.

Demonstrates a basic Orval configuration for generating a React Query client with mock data and a custom Axios mutator, then how to run it via an npm script.

import { defineConfig } from 'orval'; export default defineConfig({ petstore: { input: 'https://petstore.swagger.io/v2/swagger.json', output: { mode: 'split', target: 'src/api/endpoints/petstore.ts', schemas: 'src/api/model', client: 'react-query', // or 'axios', 'fetch', 'svelte-query', 'vue-query' mock: true, clean: true, override: { mutator: { path: './src/api/mutator/custom-instance.ts', name: 'customInstance', }, operations: { listPets: { mutation: true, query: true, }, }, }, }, hooks: { afterAllFilesWrite: 'prettier --write', }, }, }); // src/api/mutator/custom-instance.ts import Axios, { AxiosRequestConfig } from 'axios'; export const AXIOS_INSTANCE = Axios.create({ baseURL: 'https://petstore.swagger.io/v2' }); export const customInstance = <T>(config: AxiosRequestConfig, options?: AxiosRequestConfig): Promise<T> => { return AXIOS_INSTANCE({ ...config, ...options }).then((res) => res.data); }; export default customInstance; // package.json (scripts) // { // "scripts": { // "generate-api": "orval" // } // } // // To run: `npm run generate-api` or `npx orval`

orval --version

Debug

Known issues

breakingStarting from Orval v8.5.0, Faker.js (or `@faker-js/faker`) is no longer an inlined dependency and becomes an optional peer dependency. If your configuration uses mock generation, you must explicitly install a compatible version of `faker` in your project.

fix

Install `@faker-js/faker` as a dev dependency: `npm install -D @faker-js/faker` or `yarn add -D @faker-js/faker`.

affects: >=8.5.0

gotchaOrval lists `prettier` as a peer dependency. While not strictly required to run Orval, it is essential for formatting the generated code, especially if you use the `afterAllFilesWrite` hook for consistent code style.

fix

Ensure `prettier` is installed in your project: `npm install -D prettier` or `yarn add -D prettier`.

affects: >=3.0.0

gotchaOrval has a minimum Node.js engine requirement of `>=18.17.0`. Running Orval in environments with older Node.js versions will result in execution failures.

fix

Upgrade your Node.js environment to version 18.17.0 or newer. Consider using a Node Version Manager (nvm) for easy switching.

affects: >=8.0.0

gotchaFrequent updates to Orval's internal schema parsing and code generation logic, as seen in various patch notes (e.g., 'broken model imports', 'correct schema import canonic'), can sometimes lead to unexpected changes or breakages in the generated client code's imports or type definitions across minor versions, requiring review after updates.

fix

After upgrading Orval, carefully review generated client code for import resolution issues or type discrepancies. Refer to the Orval changelog for specific migration details for each minor release.

affects: >=8.0.0

Errors

Common errors & fixes

Error: Cannot find module 'faker' or Cannot find package 'faker'

Attempting to generate mocks with Orval v8.5.0 or newer without explicitly installing Faker.js.

fix

Install Faker.js: `npm install -D @faker-js/faker`.

Error: ENOENT: no such file or directory, stat 'openapi.yaml'

The input OpenAPI specification file specified in `orval.config.ts` does not exist at the given path.

fix

Verify the `input` path in your Orval configuration, ensuring the file exists and the path is correct relative to where Orval is executed.

Orval: Config file not found. Please create one, for example 'orval.config.ts'.

Orval command was executed without a recognized configuration file (e.g., `orval.config.ts`, `orval.config.js`) in the current or parent directories.

fix

Create an `orval.config.ts` or `orval.config.js` file in your project root or specify its path using the `--config` flag.

TypeError: (0 , import_core.defineConfig) is not a function

CommonJS (require) syntax is used to import `defineConfig` in an environment configured for ESM, or there's a misconfiguration with TypeScript's module resolution.

fix

Ensure your `orval.config.ts` uses ESM import syntax (`import { defineConfig } from 'orval';`) and your `tsconfig.json`'s `module` option is set appropriately (e.g., `"ESNext"` or `"NodeNext"`).

Upgrade

Version history

0.0.9latest on npm

Audit

Dependencies

prettierrequiredRequired for code formatting of generated files, especially when using the `afterAllFilesWrite` hook for consistent output styling.

@faker-js/fakeroptionalBecomes an optional peer dependency for mock generation starting from v8.5.0. Users relying on mock features must install it explicitly.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/orval-labs/orval ↗

packagehttps://www.npmjs.com/package/orval ↗

homepagehttps://orval.dev ↗