Orval - Generate type-safe API clients from OpenAPI

Integrate Orval code generation into your build processes, scripts, or tools.

Basic Usage

import orval from 'orval';

// Generate using a config file path
await orval('./orval.config.js');

// Generate using current directory's orval config
await orval();

Or use the named export:

import { generate } from 'orval';

await generate('./orval.config.js');

Direct Configuration

Pass a configuration object directly:

import { generate, type Options } from 'orval';

const config: Options = {
  input: {
    target: './api-spec.yaml',
  },
  output: {
    target: './src/api.ts',
    client: 'axios',
  },
};

await generate(config);

Global Options Override

Override config settings with global options. See the GlobalOptions interface for all available options.

import { generate, type GlobalOptions } from 'orval';

const globalOptions: GlobalOptions = {
  // File watching
  watch: true, // Enable watch mode (boolean)
  // watch: './specs/**/*.yaml',        // Watch specific file pattern (string)
  // watch: ['./specs/*.yaml'],         // Watch multiple patterns (string[])

  // Output control
  clean: true, // Clean all output directories (boolean)
  // clean: ['./src/api', './types'],   // Clean specific directories (string[])
  output: './src/generated', // Override output directory

  // Code formatting (only one formatter can be used at a time)
  formatter: 'prettier', // 'prettier' | 'biome' | 'oxfmt'

  // HTTP client configuration
  client: 'fetch', // Override HTTP client
  httpClient: 'fetch', // HTTP implementation: 'axios' | 'fetch'

  // Generation mode
  mode: 'split', // Output mode: 'single' | 'split' | 'tags' | 'tags-split'

  // Mock data generation
  mock: true, // Enable mock data generation
  // mock: { generators: [{ type: 'msw', delay: 1000 }] },  // Configure mock options

  // TypeScript configuration
  tsconfig: './tsconfig.json', // Custom tsconfig path
  // tsconfig: { compilerOptions: {...} },  // Inline tsconfig

  // Package configuration
  packageJson: './package.json',
  input: './api-spec.yaml',

  // Error handling
  throwOnError: true, // Throw initial generation errors instead of only logging them
};

await generate('./orval.config.js', process.cwd(), globalOptions);

Custom Workspace

Specify a custom workspace directory:

import { generate } from 'orval';

const workspace = '/path/to/your/project';
await generate('./orval.config.js', workspace);

Function Signature

function generate(
  optionsExport?: string | OptionsExport,
  workspace?: string,
  options?: GlobalOptions,
): Promise<void>;

Parameters:

optionsExport: Path to config file or configuration object
workspace: Working directory (defaults to process.cwd())
options: Global options to override config settings

By default, generate() logs initial generation errors and resolves after processing the configured project or projects. Set throwOnError when a script needs to catch initial generation failures and decide how to handle them:

import { generate, logError } from 'orval';

try {
  await generate('./orval.config.js', process.cwd(), {
    throwOnError: true,
  });
} catch (error) {
  logError(error);
  process.exit(1);
}

When a config file contains multiple projects, throwOnError stops on the first generation error during the initial run instead of continuing with later projects. Watch mode generation errors are still logged after the watcher has started.

Watch Mode

import { generate } from 'orval';

// Enable watch mode
await generate('./orval.config.js', process.cwd(), {
  watch: true,
});

// Watch specific files/directories
await generate('./orval.config.js', process.cwd(), {
  watch: ['./specs/*.yaml', './src/custom-types.ts'],
});

Build Scripts Integration

package.json

{
  "scripts": {
    "generate": "node scripts/generate-api.js",
    "dev": "npm run generate && next dev",
    "build": "npm run generate && next build"
  }
}

scripts/generate-api.js

const { generate } = require('orval');

async function main() {
  try {
    await generate();
    console.log('API client generated successfully');
  } catch (error) {
    console.error('Failed to generate API client:', error);
    process.exit(1);
  }
}

main();

Programmatic API