Skip to content

Commit efa858c

Browse files
committed
docs(fetch): add useRuntimeFetcher guide to output configuration reference
Add documentation for the option introduced in #3119. Covers: - What the option does: adds to request functions and to query/mutation/prefetch options - Which clients are affected: , , , - Which clients are NOT affected: axios-based clients, custom mutators, (Angular HttpClient) - SWR behavior: request functions receive but hook options do not include - Generated output examples verified against actual orval output - Usage examples for SvelteKit and Next.js App Router Signed-off-by: zeriong <jaeryong95@gmail.com>
1 parent b54a607 commit efa858c

1 file changed

Lines changed: 122 additions & 0 deletions

File tree

  • docs/content/docs/reference/configuration

docs/content/docs/reference/configuration/output.mdx

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1088,6 +1088,128 @@ Custom JSON reviver function (useful for date parsing).
10881088

10891089
Enable Zod runtime validation for fetch client responses. Requires `schemas: { type: 'zod' }`. When enabled, JSON responses are validated via `Schema.parse()` before being returned.
10901090

1091+
### useRuntimeFetcher
1092+
1093+
**Type:** `Boolean`
1094+
**Default:** `false`
1095+
1096+
Allow injecting a custom `fetch` function at runtime. When enabled:
1097+
1098+
- Every generated request function gains an optional `fetchFn?: typeof globalThis.fetch` parameter and calls `(fetchFn ?? fetch)(...)` instead of `fetch(...)`.
1099+
- For query clients (`react-query`, `vue-query`, `svelte-query`) with `httpClient: 'fetch'`, every generated query options helper, `useQuery` hook, `useMutation` hook, and prefetch function also gains a `fetcher?: typeof globalThis.fetch` field in its options type.
1100+
1101+
Applies to the `fetch` client and all fetch-based query clients (`react-query`, `vue-query`, `svelte-query`). Has no effect on axios-based clients or any operation that uses a custom mutator.
1102+
1103+
For the SWR client, the underlying request functions receive `fetchFn`, but SWR hook options do not include a `fetcher` field.
1104+
1105+
The `angular` client (Angular HttpClient) is not affected.
1106+
1107+
```ts title="orval.config.ts"
1108+
// With a query client (react-query / vue-query / svelte-query)
1109+
export default defineConfig({
1110+
petstore: {
1111+
output: {
1112+
client: 'react-query',
1113+
httpClient: 'fetch',
1114+
override: {
1115+
fetch: {
1116+
useRuntimeFetcher: true,
1117+
},
1118+
},
1119+
},
1120+
},
1121+
});
1122+
1123+
// With the standalone fetch client
1124+
export default defineConfig({
1125+
petstore: {
1126+
output: {
1127+
client: 'fetch',
1128+
override: {
1129+
fetch: {
1130+
useRuntimeFetcher: true,
1131+
},
1132+
},
1133+
},
1134+
},
1135+
});
1136+
```
1137+
1138+
**Generated output (request function)**
1139+
1140+
```ts
1141+
export const listPets = async (
1142+
params: ListPetsParams,
1143+
options?: RequestInit,
1144+
fetchFn?: typeof globalThis.fetch,
1145+
): Promise<listPetsResponse> => {
1146+
const res = await (fetchFn ?? fetch)(getListPetsUrl(params), {
1147+
...options,
1148+
method: 'GET',
1149+
});
1150+
// ...
1151+
};
1152+
```
1153+
1154+
**Generated output (query / mutation / prefetch options)**
1155+
1156+
All generated helpers accept the same `fetcher` field:
1157+
1158+
```ts
1159+
// useQuery
1160+
export const useListPets = (
1161+
params: ListPetsParams,
1162+
options?: {
1163+
query?: UseQueryOptions<...>;
1164+
fetch?: RequestInit;
1165+
fetcher?: typeof globalThis.fetch;
1166+
},
1167+
) => { ... };
1168+
1169+
// useMutation
1170+
export const useCreatePets = (
1171+
options?: {
1172+
mutation?: UseMutationOptions<...>;
1173+
fetch?: RequestInit;
1174+
fetcher?: typeof globalThis.fetch;
1175+
},
1176+
) => { ... };
1177+
1178+
// prefetch
1179+
export const prefetchListPetsQuery = async (
1180+
queryClient: QueryClient,
1181+
params: ListPetsParams,
1182+
options?: {
1183+
query?: UseQueryOptions<...>;
1184+
fetch?: RequestInit;
1185+
fetcher?: typeof globalThis.fetch;
1186+
},
1187+
) => { ... };
1188+
```
1189+
1190+
**Common use cases**
1191+
1192+
This is useful in any context where you need to inject a custom `fetch` implementation — for example, SSR frameworks that provide a request-scoped `fetch`:
1193+
1194+
```ts
1195+
// SvelteKit — +page.ts
1196+
export const load = async ({ fetch }) => {
1197+
const queryClient = new QueryClient();
1198+
await prefetchListPetsQuery(queryClient, params, { fetcher: fetch });
1199+
return { queryClient };
1200+
};
1201+
1202+
// Next.js App Router — page.tsx (server component)
1203+
import { cache } from 'react';
1204+
const getQueryClient = cache(() => new QueryClient());
1205+
1206+
export default async function Page() {
1207+
const queryClient = getQueryClient();
1208+
await prefetchListPetsQuery(queryClient, params, { fetcher: fetch });
1209+
// ...
1210+
}
1211+
```
1212+
10911213
---
10921214

10931215
## Runtime validation support matrix

0 commit comments

Comments
 (0)