Migration Guide to v8

This guide explains the changes required to migrate from Orval v7 to v8.

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>