OrvalOrval

Upgrading to v8

Migration guide for Orval v8

v8 brings significant improvements focused on modern JavaScript ecosystem support and enhanced Zod schema integration.

New Features

ESM (ECMAScript Modules)

The entire project has migrated from CommonJS to ESM.

Key Changes:

  • All packages use "type": "module" in package.json
  • Import/export syntax instead of require()
  • Node.js 22.18 or higher required
# Rename config to .mjs
mv orval.config.js orval.config.mjs

# Or add to package.json
# "type": "module"

Default HTTP Client: Fetch

The default HTTP client changed from axios to fetch for smaller bundle sizes.

To continue using axios:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      httpClient: 'axios',
      target: './src/api',
    },
  },
});

New Framework Support

Angular Query:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      client: 'angular-query',
      target: './src/api',
    },
  },
});

Solid Query / SolidStart:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      client: 'solid-query',
      target: './src/api',
    },
  },
});

Enhanced Zod Integration

Schema Type Selection:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      schemas: {
        path: './model',
        type: 'zod', // 'typescript' | 'zod'
      },
    },
  },
});

Runtime Validation:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      schemas: { type: 'zod' },
      client: 'fetch',
      override: {
        fetch: {
          runtimeValidation: true,
        },
      },
    },
  },
});

React Compiler Support

TanStack Query (React Query) updated to work correctly with React Compiler.

Combined Types Inlining

anyOf, oneOf, and allOf are now inlined by default:

// Before
export type Response401OneOf = { defined: true; ... };
export type Response401OneOfTwo = { defined: false; ... };
export type Response401 = Response401OneOf | Response401OneOfTwo;

// After
export type Response401 = { defined: true; ... } | { defined: false; ... };

To maintain previous behavior:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      override: {
        aliasCombinedTypes: true,
      },
    },
  },
});

Breaking Changes

1. ESM Migration

The project has been fully converted from CommonJS to ESM.

Key Changes:

  • Node.js 22.18+ required
  • All packages now use "type": "module" in package.json
  • Import/export syntax instead of require()

How to migrate:

# Check your Node.js version
node --version  # Should be >= 22.18.0

Update configuration files (either rename or add type):

mv orval.config.js orval.config.mjs

Or add to package.json:

{
  "type": "module"
}

Update imports if using Orval programmatically:

- const { generate } = require('orval');
+ import { generate } from 'orval';

Update dynamic imports:

- const config = require('./orval.config.js');
+ const config = await import('./orval.config.js');

.ts files require no changes if written in ESM style.

Benefits:

  • Better tree-shaking (unused code elimination)
  • Native browser support
  • Async module loading
  • Stricter module boundaries

2. Default httpClient Changed to fetch

Explicitly set httpClient: 'axios' if needed.

3. Removed override.fetch.explode

Specify explode directly in your OpenAPI specification.

4. Mock delay default changed to false

Set delay: 1000 explicitly if needed.

5. Removed override.coerceTypes

Use override.zod.coerce instead:

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      override: {
        zod: {
          coerce: {
            param: true,
            query: true,
            header: true,
            body: true,
            response: true,
          },
        },
      },
    },
  },
});

6. Removed override.useNativeEnums

Use enumGenerationType: 'enum' instead.

7. Zod Schema Naming Changed to PascalCase

- export const createPetsBody = zod.object({ ... })
+ export const CreatePetsBody = zod.object({ ... })

8. SWR Error Types Not Generated by Default

Custom error type aliases (e.g., ListPetsQueryError, CreatePetsMutationError) are no longer generated by default.

orval.config.ts
export default defineConfig({
  petstore: {
    output: {
      override: {
        swr: {
          generateErrorTypes: true,
        },
      },
    },
  },
});

Other Improvements

Variable Expansion in Fetch Client Headers

Variable expansion is now supported in override.requestOptions.headers.

Bug Fixes

  • Zod nullable + $ref support (OpenAPI 3.1 compliance)
  • oneOf/anyOf common properties support
  • Date parameter fixes
  • Svelte 5 reactivity support

Release Timeline

VersionRelease DateMain Changes
v8.0.0-rc.02025-10-27ESM migration, basic Breaking Changes
v8.0.0-rc.12025-10-30ESM module import support (jiti)
v8.0.0-rc.22025-11-14Bug fixes
v8.0.0-rc.32025-12-06Bug fixes
v8.0.0-rc.42025-12-14Zod schema features
v8.0.0-rc.52025-12-23Angular Query, Zod fixes

Acknowledgments

We sincerely thank all contributors, followers, and users for your support. Your encouragement drives us to keep improving. 🙏

If you would like to support Orval's ongoing development, please consider becoming a sponsor on Open Collective.

Full Example

Complete configuration example

On this page

New FeaturesESM (ECMAScript Modules)Default HTTP Client: FetchNew Framework SupportEnhanced Zod IntegrationReact Compiler SupportCombined Types InliningBreaking Changes1. ESM Migration2. Default httpClient Changed to fetch3. Removed override.fetch.explode4. Mock delay default changed to false5. Removed override.coerceTypes6. Removed override.useNativeEnums7. Zod Schema Naming Changed to PascalCase8. SWR Error Types Not Generated by DefaultOther ImprovementsVariable Expansion in Fetch Client HeadersBug FixesRelease TimelineAcknowledgments