docs: v8 migration guide (#2479)

* docs: add v8 migration guide

* docs: fix indent level

* docs: remove `paramsSerializerOptions` section

* docs: add convert `ESM` section

* docs: add `Removed TanStack Query v3 support` section

Author: soartec-lab

docs/src/pages/guides/migration-v8.mdx

@@ -0,0 +1,223 @@
+---
+id: migration-v8
+title: 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:
+
+```bash
+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:
+
+```bash
+mv orval.config.js orval.config.mjs
+```
+
+2. Or add `"type": "module"` to your package.json:
+
+```diff:package.json
+{
+  "name": "your-project",
++ "type": "module",
+  ...
+}
+```
+
+#### Update imports in your code
+
+If you were importing Orval programmatically:
+
+```diff:your-script.js
+- const { generate } = require('orval');
++ import { generate } from 'orval';
+```
+
+#### Update dynamic imports
+
+If you were using dynamic imports:
+
+```diff:your-script.js
+- 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:
+
+```diff:orval.config.ts
+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.
+
+```diff:petstore.yaml
+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.
+
+```diff:orval.config.ts
+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`.
+
+```diff:orval.config.ts
+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`.
+
+```diff:orval.config.ts
+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`:
+
+```bash
+npm uninstall react-query
+npm install @tanstack/react-query@latest
+```
+
+#### Vue Query
+
+Upgrade from `vue-query` to `@tanstack/vue-query`:
+
+```bash
+npm uninstall vue-query
+npm install @tanstack/vue-query@latest
+```
+
+#### Svelte Query
+
+Upgrade from `@sveltestack/svelte-query` to `@tanstack/svelte-query`:
+
+```bash
+npm uninstall @sveltestack/svelte-query
+npm install @tanstack/svelte-query@latest
+```
+
+### Official migration guides
+
+- [TanStack Query v4 Migration Guide](https://tanstack.com/query/v4/docs/react/guides/migrating-to-react-query-4)
+- [TanStack Query v5 Migration Guide](https://tanstack.com/query/latest/docs/react/guides/migrating-to-v5)

docs/src/pages/reference/configuration/output.mdx

@@ -1141,7 +1141,7 @@ export const createPets = async (
 };
 ```
 
-##### jsonReviver
+#### jsonReviver
 
 Type: `String` or `Object`