# Upgrading to 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**

```bash
# 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:

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

### New Framework Support

**Angular Query:**

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

**Solid Query / SolidStart:**

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

### Enhanced Zod Integration

**Schema Type Selection:**

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

**Runtime Validation:**

```ts
export default defineConfig({
  petstore: {
    output: {
      schemas: { type: 'zod' },
      client: 'fetch',
      override: {
        fetch: {
          runtimeValidation: { strategy: 'both' },
        },
      },
    },
  },
});
```

`runtimeValidation: true` remains supported as shorthand for
`{ strategy: 'throw' }`.

### 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:

```ts
// 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:

```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:**

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

Update configuration files (either rename or add type):

```bash
mv orval.config.js orval.config.mjs
```

Or add to package.json:

```json
{
  "type": "module"
}
```

Update imports if using Orval programmatically:

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

Update dynamic imports:

```diff
- 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:

```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

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

### 8. `input.validation` Removed

The `input.validation` option no longer exists. Specs are always validated and
the validator (`@scalar/openapi-parser`) is now stricter than the v7 IBM
validator — what previously surfaced as warnings is now a hard error.

If your spec is malformed and you can repair it, use `input.override.transformer`
(it now runs **before** validation, so you can fix issues in-place). As a last
resort, opt out of validation entirely with `input.unsafeDisableValidation`:

```ts
export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
      unsafeDisableValidation: true,
    },
  },
});
```

See [`input.unsafeDisableValidation`](/docs/reference/configuration/input#unsafedisablevalidation)
and [`input.override.transformer`](/docs/reference/configuration/input#transformer)
for details.

> **Note:**
> If your spec is OpenAPI 2.0 (Swagger), `override.transformer` now receives
> the 2.0 document — previously it ran on the upgraded 3.1 form. Adjust
> transformers that assumed 3.x shape accordingly.

### 9. SWR Error Types Not Generated by Default

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

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

### 10. `output.mock` now uses a `generators` array

Previously, `output.mock` accepted either `true` or a flat options object (`{ type: 'msw', delay: 1000, locale: 'fr', ... }`). All options lived on a single object and `type: 'msw'` was the only supported type.

Now, `output.mock` wraps generator entries in a `generators` array. Each entry produces its own output file (e.g. `.msw.ts`, `.faker.ts`). This enables multiple independent mock generators from a single config.

#### `mock: true` behavior change

`mock: true` previously emitted only MSW handlers. It now emits **both** MSW handlers (`.msw.ts`) and Faker data factories (`.faker.ts`). To keep the old behavior (MSW only), use the explicit form:

```ts
output: {
  mock: { generators: [{ type: 'msw' }] },
}
```

#### Migrating a flat options object

All per-generator options (`delay`, `useExamples`, `locale`, `baseUrl`, etc.) move inside the generator entry:

```diff
output: {
- mock: { type: 'msw', delay: 1000, useExamples: true, locale: 'fr' },
+ mock: {
+   generators: [{ type: 'msw', delay: 1000, useExamples: true, locale: 'fr' }],
+ },
}
```

#### `indexMockFiles` moves to the wrapper

`indexMockFiles` is now a collection-level option rather than a per-generator option:

```diff
output: {
- mock: { type: 'msw', indexMockFiles: true },
+ mock: { indexMockFiles: true, generators: [{ type: 'msw' }] },
}
```

#### New: Faker-only output

To generate only Faker data factories without MSW handlers:

```ts
output: {
  mock: { generators: [{ type: 'faker' }] },
}
```

## 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

| Version | Release Date | Main Changes |
| --- | --- | --- |
| v8.0.0-rc.0 | 2025-10-27 | ESM migration, basic Breaking Changes |
| v8.0.0-rc.1 | 2025-10-30 | ESM module import support (jiti) |
| v8.0.0-rc.2 | 2025-11-14 | Bug fixes |
| v8.0.0-rc.3 | 2025-12-06 | Bug fixes |
| v8.0.0-rc.4 | 2025-12-14 | Zod schema features |
| v8.0.0-rc.5 | 2025-12-23 | Angular 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](https://opencollective.com/orval).