Integration

Programmatic Usage

Orval provides a powerful programmatic API that allows you to integrate code generation into your build processes, scripts, or tools.

Basic Usage

Using the Default Export

1import orval from 'orval';
2
3// Generate using a config file path
4await orval('./orval.config.js');
5
6// Generate using current directory's orval config
7await orval();

Using the Named Export

1import { generate } from 'orval';
2
3// Same functionality as default export
4await generate('./orval.config.js');

Advanced Usage

Direct Configuration Object

You can pass a configuration object directly instead of using a config file:

1import { generate, type Options } from 'orval';
2
3const config: Options = {
4  input: {
5    target: './api-spec.yaml',
6  },
7  output: {
8    target: './src/api.ts',
9    client: 'axios',
10  },
11};
12
13await generate(config);

Global Options Override

Pass global options to override config file settings. See the complete GlobalOptions interface for all available options.

1import { generate, type GlobalOptions } from 'orval';
2
3const globalOptions: GlobalOptions = {
4  // File watching
5  watch: true,                    // Enable watch mode (boolean)
6  
7  // OR
8  // watch: './specs/**/*.yaml',     // Watch specific file pattern (string)
9  
10  // OR
11  // watch: ['./specs/*.yaml', './src/types.ts'], // Watch multiple patterns (string[])
12  
13  // Output control
14  clean: true,                    // Clean all output directories (boolean)
15  
16  // OR
17  // clean: ['./src/api', './types'], // Clean specific directories (string[])
18  
19  output: './src/generated',      // Override output directory
20  
21  // Code formatting
22  prettier: true,                 // Format with Prettier [Pretter Output Options](https://orval.dev/reference/configuration/output#prettier)
23  biome: true,                   // Format with Biome [Biome Output Options](https://orval.dev/reference/configuration/output#biome)
24  
25  // HTTP client configuration 
26  client: 'fetch',               // Override HTTP client: 'axios' | 'angular' | 'fetch' | 'swr' | 'react-query' | 'vue-query' | 'svelte-query' [Client Output Options](https://orval.dev/reference/configuration/output#client)
27  httpClient: 'fetch',           // HTTP implementation: 'axios' | 'fetch' [HttpClient Output Options](https://orval.dev/reference/configuration/output#httpclient)
28  
29  // Generation mode
30  mode: 'split',                 // Output mode: 'single' | 'split' | 'tags' | 'tags-split'
31  
32  // Mock data generation
33  mock: true,                    // Enable mock data generation (boolean)
34  
35  // OR 
36  // mock: {                        // Configure mock options (GlobalMockOptions)
37  //   type: 'msw',
38  //   delay: 1000,
39  // },
40  
41  // TypeScript configuration
42  // Use EITHER a custom tsconfig path (string)... 
43  tsconfig: './tsconfig.json',   // Custom tsconfig path (string)
44  // ...OR an inline tsconfig object:  
45  // tsconfig: {  
46  //   compilerOptions: {  
47  //     target: 'ES2020',  
48  //     esModuleInterop: true,  
49  //   },  
50  // },
51  
52  // Package configuration
53  packageJson: './package.json', // Custom package.json path
54  input: './api-spec.yaml',      // Override input specification
55};
56
57await generate('./orval.config.js', process.cwd(), globalOptions);

Custom Workspace

Specify a custom workspace directory (default process.cwd()):

1import { generate } from 'orval';
2
3const workspace = '/path/to/your/project';
4await generate('./orval.config.js', workspace);

Function Signature

1function generate(
2  optionsExport?: string | OptionsExport,
3  workspace?: string,
4  options?: GlobalOptions,
5): Promise<void>

Parameters

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

Watch Mode

Enable file watching for automatic regeneration:

1import { generate } from 'orval';
2
3// Enable watch mode via global options
4await generate('./orval.config.js', process.cwd(), { 
5  watch: true 
6});
7
8// Watch specific files/directories
9await generate('./orval.config.js', process.cwd(), { 
10  watch: ['./specs/*.yaml', './src/custom-types.ts']
11});

Build Scripts Integration

npm/yarn scripts

1{
2  "scripts": {
3    "generate": "node scripts/generate-api.js",
4    "dev": "npm run generate && next dev",
5    "build": "npm run generate && next build"
6  }
7}

1// scripts/generate-api.js
2const { generate } = require('orval');
3
4async function main() {
5  try {
6    await generate();
7    console.log('API client generated successfully');
8  } catch (error) {
9    console.error('Failed to generate API client:', error);
10    process.exit(1);
11  }
12}
13
14main();