{"id":11504,"library":"orval","title":"Orval OpenAPI TypeScript Client Generator","description":"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.","status":"active","version":"8.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/orval-labs/orval","tags":["javascript","rest","client","swagger","open-api","fetch","data fetching","code-generation","angular","typescript"],"install":[{"cmd":"npm install orval","lang":"bash","label":"npm"},{"cmd":"yarn add orval","lang":"bash","label":"yarn"},{"cmd":"pnpm add orval","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for code formatting of generated files, especially when using the `afterAllFilesWrite` hook for consistent output styling.","package":"prettier","optional":false},{"reason":"Becomes an optional peer dependency for mock generation starting from v8.5.0. Users relying on mock features must install it explicitly.","package":"@faker-js/faker","optional":true}],"imports":[{"note":"Primarily used in `orval.config.ts` for type-safe configuration. Orval is primarily an ESM package.","wrong":"const defineConfig = require('orval').defineConfig;","symbol":"defineConfig","correct":"import { defineConfig } from 'orval';"},{"note":"Used for type hinting the configuration object when not using `defineConfig` directly or for extending configurations.","symbol":"OrvalConfig","correct":"import type { OrvalConfig } from 'orval';"},{"note":"Type definition for configuring lifecycle hooks within the Orval configuration.","symbol":"HooksOptions","correct":"import type { HooksOptions } from 'orval';"}],"quickstart":{"code":"import { defineConfig } from 'orval';\n\nexport default defineConfig({\n  petstore: {\n    input: 'https://petstore.swagger.io/v2/swagger.json',\n    output: {\n      mode: 'split',\n      target: 'src/api/endpoints/petstore.ts',\n      schemas: 'src/api/model',\n      client: 'react-query', // or 'axios', 'fetch', 'svelte-query', 'vue-query'\n      mock: true,\n      clean: true,\n      override: {\n        mutator: {\n          path: './src/api/mutator/custom-instance.ts',\n          name: 'customInstance',\n        },\n        operations: {\n          listPets: {\n            mutation: true,\n            query: true,\n          },\n        },\n      },\n    },\n    hooks: {\n      afterAllFilesWrite: 'prettier --write',\n    },\n  },\n});\n\n// src/api/mutator/custom-instance.ts\nimport Axios, { AxiosRequestConfig } from 'axios';\n\nexport const AXIOS_INSTANCE = Axios.create({ baseURL: 'https://petstore.swagger.io/v2' });\n\nexport const customInstance = <T>(config: AxiosRequestConfig, options?: AxiosRequestConfig): Promise<T> => {\n  return AXIOS_INSTANCE({ ...config, ...options }).then((res) => res.data);\n};\n\nexport default customInstance;\n\n// package.json (scripts)\n// {\n//   \"scripts\": {\n//     \"generate-api\": \"orval\"\n//   }\n// }\n//\n// To run: `npm run generate-api` or `npx orval`","lang":"typescript","description":"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."},"warnings":[{"fix":"Install `@faker-js/faker` as a dev dependency: `npm install -D @faker-js/faker` or `yarn add -D @faker-js/faker`.","message":"Starting 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.","severity":"breaking","affected_versions":">=8.5.0"},{"fix":"Ensure `prettier` is installed in your project: `npm install -D prettier` or `yarn add -D prettier`.","message":"Orval 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to version 18.17.0 or newer. Consider using a Node Version Manager (nvm) for easy switching.","message":"Orval 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.","severity":"gotcha","affected_versions":">=8.0.0"},{"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.","message":"Frequent 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.","severity":"gotcha","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install Faker.js: `npm install -D @faker-js/faker`.","cause":"Attempting to generate mocks with Orval v8.5.0 or newer without explicitly installing Faker.js.","error":"Error: Cannot find module 'faker' or Cannot find package 'faker'"},{"fix":"Verify the `input` path in your Orval configuration, ensuring the file exists and the path is correct relative to where Orval is executed.","cause":"The input OpenAPI specification file specified in `orval.config.ts` does not exist at the given path.","error":"Error: ENOENT: no such file or directory, stat 'openapi.yaml'"},{"fix":"Create an `orval.config.ts` or `orval.config.js` file in your project root or specify its path using the `--config` flag.","cause":"Orval command was executed without a recognized configuration file (e.g., `orval.config.ts`, `orval.config.js`) in the current or parent directories.","error":"Orval: Config file not found. Please create one, for example 'orval.config.ts'."},{"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\"`).","cause":"CommonJS (require) syntax is used to import `defineConfig` in an environment configured for ESM, or there's a misconfiguration with TypeScript's module resolution.","error":"TypeError: (0 , import_core.defineConfig) is not a function"}],"ecosystem":"npm"}