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"

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
  1. Or add "type": "module" to your package.json:
{
  "name": "your-project",
+ "type": "module",
  ...
}

Update imports in your code

If you were importing Orval programmatically:

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

Update dynamic imports

If you were using dynamic imports:

- const config = require('./orval.config.js');
+ 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:

export default {
  petstore: {
    output: {
+     httpClient: 'axios', // Explicitly specify
      target: './src/api',
    },
    input: {
      target: './petstore.yaml',
    },
  },
};

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.

paths:
  /pets:
    get:
      parameters:
        - name: tags
          in: query
+         explode: true
          schema:
            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.

export default {
  petstore: {
    output: {
      mock: {
+       delay: 1000, // In milliseconds
      },
    },
  },
};

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.

export default {
  petstore: {
    output: {
      override: {
-       coerceTypes: true
+       zod: {
+         coerce: {
+           param: true,
+           query: true,
+           header: true,
+           body: true,
+           response: true
+         }
+       }
      },
    },
  },
};

6. Removed override.useNativeEnums

This was removed as it has been integrated into enumGenerationType.

How to maintain compatibility

Use enumGenerationType.

export default {
  petstore: {
    output: {
      override: {
-       useNativeEnums: true
+       enumGenerationType: 'enum'
      },
    },
  },
};

7. Removed TanStack Query v3 support

Support for TanStack Query v3 (react-query, vue-query, svelte-query) has been removed. TanStack Query v3 is no longer maintained, and v4/v5 provide significant API improvements.

How to migrate

React Query

Upgrade from react-query to @tanstack/react-query:

npm uninstall react-query
npm install @tanstack/react-query@latest

Vue Query

Upgrade from vue-query to @tanstack/vue-query:

npm uninstall vue-query
npm install @tanstack/vue-query@latest

Svelte Query

Upgrade from @sveltestack/svelte-query to @tanstack/svelte-query:

npm uninstall @sveltestack/svelte-query
npm install @tanstack/svelte-query@latest

Official migration guides

Edit this page on GitHub
Was this page helpful?