feat(react-query): add httpClientInjection: 'reactQueryMeta' option

docs/content/docs/guides/react-query.mdx

@@ -128,6 +128,61 @@ export default defineConfig({
 });
 ```
 
+## Axios Instance Injection
+
+Use `httpClientInjection: 'reactQueryMeta'` to inject a configured axios instance at runtime via the QueryClient. This is useful when publishing generated code as an NPM package — consumers provide their own axios with interceptors, auth, and base URL.
+
+In your `orval.config.ts`:
+
+```ts
+import { defineConfig } from 'orval';
+
+export default defineConfig({
+  petstore: {
+    output: {
+      client: 'react-query',
+      httpClient: 'axios',
+      httpClientInjection: 'reactQueryMeta',
+    },
+    input: {
+      target: './petstore.yaml',
+    },
+  },
+});
+```
+
+In your app entry point:
+
+```tsx
+import axios from 'axios';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useListPets } from './api/endpoints/petstore';
+
+const axiosInstance = axios.create({ baseURL: 'https://api.example.com' });
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { meta: { axiosInstance } },
+    mutations: { meta: { axiosInstance } },
+  },
+});
+
+function Pets() {
+  const { data } = useListPets();
+  return <ul>{data?.map((pet) => <li key={pet.id}>{pet.name}</li>)}</ul>;
+}
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Pets />
+    </QueryClientProvider>
+  );
+}
+```
+
+The generated hooks are SSR-compatible — prefetch works out of the box with `dehydrate()`. See the [complete example](https://github.com/orval-labs/orval/blob/master/samples/react-query/queryclient-meta).
+
 ## Full Example
 
 See the [complete React Query example](https://github.com/orval-labs/orval/blob/master/samples/react-query/basic) on GitHub.

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

@@ -77,6 +77,40 @@ export default defineConfig({
 });
 ```
 
+## httpClientInjection
+
+**Type:** `'none' | 'reactQueryMeta'`
+**Default:** `'none'`
+
+Controls how the HTTP client instance is provided to generated hooks. When set to `reactQueryMeta`, the generated hooks read the axios instance from `QueryClient.defaultOptions.meta.axiosInstance` at runtime, enabling SDK-style distribution where consumers inject their own configured instance.
+
+```ts
+export default defineConfig({
+  petstore: {
+    output: {
+      client: 'react-query',
+      httpClient: 'axios',
+      httpClientInjection: 'reactQueryMeta',
+    },
+  },
+});
+```
+
+Consumer setup:
+
+```ts
+const axiosInstance = axios.create({ baseURL: 'https://api.example.com' });
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { meta: { axiosInstance } },
+    mutations: { meta: { axiosInstance } },
+  },
+});
+```
+
+The generated hooks automatically resolve the instance via `useQueryClient()` inside `queryFn`/`mutationFn`. Falls back to default axios if not configured. Incompatible with custom `mutator`.
+
 ## schemas
 
 **Type:** `String`

packages/core/src/types.ts

@@ -36,6 +36,7 @@ export type NormalizedOutputOptions = {
   override: NormalizedOverrideOutput;
   client: OutputClient | OutputClientFunc;
   httpClient: OutputHttpClient;
+  httpClientInjection: OutputHttpClientInjection;
   clean: boolean | string[];
   docs: boolean | OutputDocsOptions;
   prettier: boolean;
@@ -235,6 +236,7 @@ export type OutputOptions = {
   override?: OverrideOutput;
   client?: OutputClient | OutputClientFunc;
   httpClient?: OutputHttpClient;
+  httpClientInjection?: OutputHttpClientInjection;
   clean?: boolean | string[];
   docs?: boolean | OutputDocsOptions;
   prettier?: boolean;
@@ -297,6 +299,14 @@ export const OutputHttpClient = {
 export type OutputHttpClient =
   (typeof OutputHttpClient)[keyof typeof OutputHttpClient];
 
+export const OutputHttpClientInjection = {
+  NONE: 'none',
+  REACT_QUERY_META: 'reactQueryMeta',
+} as const;
+
+export type OutputHttpClientInjection =
+  (typeof OutputHttpClientInjection)[keyof typeof OutputHttpClientInjection];
+
 export const OutputMode = {
   SINGLE: 'single',
   SPLIT: 'split',
@@ -771,6 +781,7 @@ export interface GlobalOptions {
   mock?: boolean | GlobalMockOptions;
   client?: OutputClient;
   httpClient?: OutputHttpClient;
+  httpClientInjection?: OutputHttpClientInjection;
   mode?: OutputMode;
   tsconfig?: string | Tsconfig;
   packageJson?: string;
@@ -1002,6 +1013,7 @@ export type ClientDependenciesBuilder = (
   httpClient?: OutputHttpClient,
   hasTagsMutator?: boolean,
   override?: NormalizedOverrideOutput,
+  httpClientInjection?: OutputHttpClientInjection,
 ) => GeneratorDependency[];
 
 export type ClientMockGeneratorImplementation = {

packages/orval/src/client.ts

@@ -89,6 +89,7 @@ export const generateClientImports: GeneratorClientImports = ({
             output.httpClient,
             hasTagsMutator,
             output.override,
+            output.httpClientInjection,
           ),
           ...imports,
         ]

packages/orval/src/utils/options.ts

@@ -32,6 +32,7 @@ import {
   type OptionsExport,
   OutputClient,
   OutputHttpClient,
+  OutputHttpClientInjection,
   OutputMode,
   type OverrideOutput,
   PropertySortOrder,
@@ -132,7 +133,7 @@ export async function normalizeOptions(
     workspace,
   );
 
-  const { clean, prettier, client, httpClient, mode, biome } = globalOptions;
+  const { clean, prettier, client, httpClient, httpClientInjection, mode, biome } = globalOptions;
 
   const tsconfig = await loadTsconfig(
     outputOptions.tsconfig || globalOptions.tsconfig,
@@ -206,6 +207,10 @@ export async function normalizeOptions(
         ((outputOptions.client ?? client) === OutputClient.ANGULAR_QUERY
           ? OutputHttpClient.ANGULAR
           : OutputHttpClient.FETCH),
+      httpClientInjection:
+        outputOptions.httpClientInjection ??
+        httpClientInjection ??
+        OutputHttpClientInjection.NONE,
       mode: normalizeOutputMode(outputOptions.mode ?? mode),
       mock,
       clean: outputOptions.clean ?? clean ?? false,
@@ -405,6 +410,20 @@ export async function normalizeOptions(
     throw new Error(chalk.red(`Config require an output target or schemas`));
   }
 
+  // Validate that httpClientInjection: 'reactQueryMeta' is not used with custom mutator
+  if (
+    normalizedOptions.output.httpClientInjection ===
+      OutputHttpClientInjection.REACT_QUERY_META &&
+    normalizedOptions.output.override?.mutator
+  ) {
+    throw new Error(
+      chalk.red(
+        `httpClientInjection: "reactQueryMeta" is incompatible with custom mutator. ` +
+          `The mutator handles the HTTP client internally, so axios injection via QueryClient meta is not supported.`,
+      ),
+    );
+  }
+
   return normalizedOptions;
 }
 

packages/query/src/client.ts

@@ -11,6 +11,7 @@ import {
   type GetterResponse,
   isSyntheticDefaultImportsAllow,
   OutputHttpClient,
+  OutputHttpClientInjection,
   pascal,
   toObjectString,
 } from '@orval/core';
@@ -43,6 +44,24 @@ export const AXIOS_DEPENDENCIES: GeneratorDependency[] = [
   },
 ];
 
+export const AXIOS_DEPENDENCIES_WITH_INSTANCE: GeneratorDependency[] = [
+  {
+    exports: [
+      {
+        name: 'axios',
+        default: true,
+        values: true,
+        syntheticDefaultImport: true,
+      },
+      { name: 'AxiosInstance' },
+      { name: 'AxiosRequestConfig' },
+      { name: 'AxiosResponse' },
+      { name: 'AxiosError' },
+    ],
+    dependency: 'axios',
+  },
+];
+
 export const ANGULAR_HTTP_DEPENDENCIES: GeneratorDependency[] = [
   {
     exports: [
@@ -384,6 +403,10 @@ export const generateAxiosRequestFunction = (
     context.output.tsconfig,
   );
 
+  const isReactQueryMeta =
+    context.output.httpClientInjection ===
+    OutputHttpClientInjection.REACT_QUERY_META;
+
   const options = generateOptions({
     route,
     body,
@@ -410,14 +433,29 @@ export const generateAxiosRequestFunction = (
 
   const queryProps = toObjectString(props, 'implementation');
 
-  const httpRequestFunctionImplementation = `${override.query.shouldExportHttpClient ? 'export ' : ''}const ${operationName} = (\n    ${queryProps} ${optionsArgs} ): Promise<AxiosResponse<${
-    response.definition.success || 'unknown'
-  }>> => {
+  // For reactQueryMeta mode, add axiosInstance as first parameter
+  const axiosInstanceParam = isReactQueryMeta
+    ? 'axiosInstance: AxiosInstance,\n    '
+    : '';
+
+  // Use axiosInstance if provided, otherwise use global axios
+  const axiosRef = isReactQueryMeta
+    ? 'axiosInstance'
+    : `axios${isSyntheticDefaultImportsAllowed ? '' : '.default'}`;
+
+  // For reactQueryMeta mode, return response.data (serializable for SSR)
+  // instead of the full AxiosResponse (which contains non-serializable functions)
+  const returnType = isReactQueryMeta
+    ? response.definition.success || 'unknown'
+    : `AxiosResponse<${response.definition.success || 'unknown'}>`;
+  const returnStatement = isReactQueryMeta
+    ? `${axiosRef}.${verb}(${options}).then(res => res.data)`
+    : `${axiosRef}.${verb}(${options})`;
+
+  const httpRequestFunctionImplementation = `${override.query.shouldExportHttpClient ? 'export ' : ''}const ${operationName} = (\n    ${axiosInstanceParam}${queryProps} ${optionsArgs} ): Promise<${returnType}> => {
     ${isVue ? vueUnRefParams(props) : ''}
     ${bodyForm}
-    return axios${
-      isSyntheticDefaultImportsAllowed ? '' : '.default'
-    }.${verb}(${options});
+    return ${returnStatement};
   }
 `;
 

packages/query/src/dependencies.test.ts

@@ -0,0 +1,74 @@
+import { OutputHttpClient, OutputHttpClientInjection } from '@orval/core';
+import { describe, expect, it } from 'vitest';
+
+import { getReactQueryDependencies } from './dependencies';
+
+describe('getReactQueryDependencies with httpClientInjection', () => {
+  const packageJson = {
+    dependencies: {
+      '@tanstack/react-query': '^5.0.0',
+    },
+  };
+
+  it('should include AxiosInstance when reactQueryMeta is enabled', () => {
+    const deps = getReactQueryDependencies(
+      false,
+      false,
+      packageJson,
+      OutputHttpClient.AXIOS,
+      false,
+      undefined,
+      OutputHttpClientInjection.REACT_QUERY_META,
+    );
+
+    const axiosDep = deps.find((d) => d.dependency === 'axios');
+    const axiosExports = axiosDep?.exports.map((e) => e.name) ?? [];
+    expect(axiosExports).toContain('AxiosInstance');
+  });
+
+  it('should not include AxiosInstance when injection is none', () => {
+    const deps = getReactQueryDependencies(
+      false,
+      false,
+      packageJson,
+      OutputHttpClient.AXIOS,
+      false,
+      undefined,
+      OutputHttpClientInjection.NONE,
+    );
+
+    const axiosDep = deps.find((d) => d.dependency === 'axios');
+    const axiosExports = axiosDep?.exports.map((e) => e.name) ?? [];
+    expect(axiosExports).not.toContain('AxiosInstance');
+  });
+
+  it('should not include AxiosInstance when httpClient is fetch', () => {
+    const deps = getReactQueryDependencies(
+      false,
+      false,
+      packageJson,
+      OutputHttpClient.FETCH,
+      false,
+      undefined,
+      OutputHttpClientInjection.REACT_QUERY_META,
+    );
+
+    const axiosDep = deps.find((d) => d.dependency === 'axios');
+    expect(axiosDep).toBeUndefined();
+  });
+
+  it('should not include axios deps when hasGlobalMutator', () => {
+    const deps = getReactQueryDependencies(
+      true,
+      false,
+      packageJson,
+      OutputHttpClient.AXIOS,
+      false,
+      undefined,
+      OutputHttpClientInjection.REACT_QUERY_META,
+    );
+
+    const axiosDep = deps.find((d) => d.dependency === 'axios');
+    expect(axiosDep).toBeUndefined();
+  });
+});