Upgrading to v8

Upgrading to v8

v8 was developed with over 150 commits during the development period (v8.0.0-rc.0 to rc.5).

Overview

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

New Features

🚀 Full Migration to ESM (ECMAScript Modules)

The entire project has been migrated from CommonJS to ESM.

Key Changes:

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

Updating configuration files:

1# Rename to .mjs extension
2mv orval.config.js orval.config.mjs
3
4# Or add to package.json
5# "type": "module"

If importing Orval programmatically:

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

If using dynamic imports:

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

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

Benefits of ESM:

• Better tree-shaking (unused code elimination)
• Native browser support
• Async module loading
• Aligns with JavaScript ecosystem standards
• Stricter module boundaries (better encapsulation and type safety)

🌐 Default HTTP Client Changed

The default HTTP client has been changed from axios to fetch.

Reasons:

• Reduced bundle size
• No additional dependencies required

To continue using axios:

1export default {
2  petstore: {
3    output: {
4      httpClient: 'axios', // Explicitly specify
5      target: './src/api',
6    },
7    input: {
8      target: './petstore.yaml',
9    },
10  },
11};

🔷 New Framework Support

Angular Query

TanStack Query for Angular is now supported.

1export default {
2  petstore: {
3    output: {
4      client: 'angular-query',
5      target: './src/api',
6    },
7    input: {
8      target: './petstore.yaml',
9    },
10  },
11};

Solid Query / SolidStart

Support for the SolidJS ecosystem has been added.

1export default {
2  petstore: {
3    output: {
4      client: 'solid-query',
5      target: './src/api',
6    },
7    input: {
8      target: './petstore.yaml',
9    },
10  },
11};

🛡️ Enhanced Zod Schema Integration

Schema Type Selection

You can now select Zod schemas using output.schemas.type.

1export default {
2  petstore: {
3    output: {
4      schemas: {
5        path: './model',
6        type: 'zod', // 'typescript' | 'zod'
7      },
8    },
9  },
10};

Generated files:

• type: 'typescript' → ./model/pet.ts
• type: 'zod' → ./model/pet.zod.ts

Runtime Validation

Runtime validation is now available for the Fetch client.

1export default {
2  petstore: {
3    output: {
4      schemas: {
5        type: 'zod',
6      },
7      client: 'fetch',
8      override: {
9        fetch: {
10          runtimeValidation: true,
11        },
12      },
13    },
14  },
15};

Generated code:

1import { PetsSchema } from './model/index.zod';
2
3export const listPets = async (params: ListPetsParams) => {
4  const res = await fetch(getListPetsUrl(params), { method: 'GET' });
5  const body = await res.text();
6  const parsedBody = body ? JSON.parse(body) : {};
7  const data = PetsSchema.parse(parsedBody); // Runtime validation
8  return { data, status: res.status, headers: res.headers };
9};

Schema Names Changed to PascalCase

Zod schema export names have been unified to PascalCase.

1- export const createPetsBody = zod.object({
2+ export const CreatePetsBody = zod.object({
3    name: zod.string(),
4    tag: zod.string()
5  })
6
7- export type CreatePetsBody = zod.infer<typeof createPetsBody>
8+ export type CreatePetsBody = zod.infer<typeof CreatePetsBody>

⚛️ React Compiler Support

TanStack Query (React Query) has been updated to fix code that was preventing React Compiler optimizations, enabling React Compiler to work correctly.

📦 Combined Types Inlining

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

Before:

1export type Response401OneOf = { defined: true; ... };
2export type Response401OneOfTwo = { defined: false; ... };
3export type Response401 = Response401OneOf | Response401OneOfTwo;

After:

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

To maintain previous behavior:

1export default {
2  petstore: {
3    output: {
4      override: {
5        aliasCombinedTypes: true,
6      },
7    },
8  },
9};

Breaking Changes

1. Converted to ESM (ECMAScript Modules)

The project has been fully converted from CommonJS to ESM. This modernizes the codebase and aligns with the JavaScript ecosystem's direction.

Key Changes

• All packages now use "type": "module" in package.json
• Import/export syntax instead of require()
• Node.js 22.18 or higher is required
• Configuration files should use .mjs extension or set "type": "module"
  • however, .ts is still the preferred format and requires no changes if written in ESM style

How to migrate

Update Node.js version

Ensure you're using Node.js 22.18 or higher:

node --version  # Should be >= 22.18.0

Update configuration files

If you're using a JavaScript configuration file, either:

1. Rename it to use .mjs extension:

mv orval.config.js orval.config.mjs

2. Or add "type": "module" to your package.json:

1{
2  "name": "your-project",
3+ "type": "module",
4  ...
5}

Update imports in your code

If you were importing Orval programmatically:

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

Update dynamic imports

If you were using dynamic imports:

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

Benefits of ESM

• Better tree-shaking: Unused code is more easily eliminated
• Native browser support: ESM works directly in modern browsers
• Async module loading: Improved performance with lazy loading
• Future-proof: Aligns with JavaScript ecosystem standards
• Stricter module boundaries: Better encapsulation and type safety

2. Changed default value of httpClient from axios to fetch

We changed the default httpClient from axios to fetch to reduce bundle size and eliminate the need for additional dependencies.

How to maintain compatibility

If you want to keep using axios, configure it as follows:

1export default {
2  petstore: {
3    output: {
4+     httpClient: 'axios', // Explicitly specify
5      target: './src/api',
6    },
7    input: {
8      target: './petstore.yaml',
9    },
10  },
11};

3. Removed override.fetch.explode option

This parameter was kept only for compatibility. Since compatibility maintenance is no longer needed in major versions, it has been removed.

How to maintain compatibility

Specify explode directly in the OpenAPI specification file.

1paths:
2  /pets:
3    get:
4      parameters:
5        - name: tags
6          in: query
7+         explode: true
8          schema:
9            type: array

4. Changed default value of override.mock.delay from 1000 to false

We disabled the default delay as it creates noise.

How to maintain compatibility

If you want to explicitly set a delay, specify it in milliseconds.

1export default {
2  petstore: {
3    output: {
4      mock: {
5+       delay: 1000, // In milliseconds
6      },
7    },
8  },
9};

5. Removed override.coerceTypes

This was removed as it has been replaced by the more flexible and explicit override.zod.coerce.

How to maintain compatibility

Use override.zod.coerce.

1export default {
2  petstore: {
3    output: {
4      override: {
5-       coerceTypes: true
6+       zod: {
7+         coerce: {
8+           param: true,
9+           query: true,
10+           header: true,
11+           body: true,
12+           response: true
13+         }
14+       }
15      },
16    },
17  },
18};

6. Removed override.useNativeEnums

This was removed as it has been integrated into enumGenerationType.

How to maintain compatibility

Use enumGenerationType.

1export default {
2  petstore: {
3    output: {
4      override: {
5-       useNativeEnums: true
6+       enumGenerationType: 'enum'
7      },
8    },
9  },
10};

7. Changed combined types generation (anyOf/oneOf/allOf)

Combined types (anyOf, oneOf, allOf) are now inlined by default instead of creating intermediate type aliases.

How to maintain compatibility

Use aliasCombinedTypes.

1export default {
2  petstore: {
3    output: {
4      override: {
5+       aliasCombinedTypes: true,
6      },
7    },
8  },
9};

8. Zod Schema Naming Convention Changed to PascalCase

All Zod schema exports now use PascalCase naming convention to align with TypeScript type definition standards.

What Changed

1- export const createPetsBody = zod.object({
2+ export const CreatePetsBody = zod.object({
3    name: zod.string(),
4    tag: zod.string()
5  })
6
7- export type CreatePetsBody = zod.infer<typeof createPetsBody>
8+ export type CreatePetsBody = zod.infer<typeof CreatePetsBody>

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

Acknowledgments

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

Looking forward to the continued growth of our community, we have launched a sponsorship program through Open Collective. If you would like to support Orval's ongoing development, please consider becoming a sponsor.