diff --git a/README.md b/README.md
index 950f5bc9..3ed1c6d3 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,7 @@ See the [documentation](https://orqc.7nohe.dev) for [CLI options](https://orqc.7
| | This library | @hey-api tanstack-query plugin | Orval | openapi-react-query |
|---|---|---|---|---|
-| `queryOptions` / `infiniteQueryOptions` factories (TanStack v5 pattern) | ✅ | ✅ | ❌ | ✅ (`$api.queryOptions`) |
+| `queryOptions` / `infiniteQueryOptions` factories (TanStack v5 pattern) | ✅ | ✅ | ✅ (`getXxxQueryOptions`) | ✅ (`$api.queryOptions`) |
| Ready-to-use hooks (`useQuery` / suspense / infinite variants) | ✅ generated per operation | ❌ (options only) | ✅ | ✅ runtime wrapper (method + path strings) |
| SSR helpers (`prefetchQuery` / `prefetchInfiniteQuery` / `ensureQueryData`) | ✅ | ❌ | Partial (`usePrefetch`) | Not provided (use `queryOptions`) |
| Hierarchical query keys for granular invalidation | ✅ | ✅ (tags) | Partial | Not documented |
@@ -93,7 +93,7 @@ See the [documentation](https://orqc.7nohe.dev) for [CLI options](https://orqc.7
| Packages added by installing the generator¹ | **9** (2.1 MB) | 51 (10.8 MB) | 89 (101.5 MB) | 35 (20.5 MB) |
| Type errors in the generated code, Stripe / GitHub APIs¹ | **0 / 0** | 274 / 0 | 219 / 1 | 0 / 0 |
-¹ Measured on 2026-11-13 on an Apple M2 with Node.js 24 (generation time is the median wall-clock time of the CLI), with 4.0.0-beta.4, `@hey-api/openapi-ts` 0.99.0, Orval 8.46.0 and openapi-typescript 7.13.0 + openapi-react-query 0.5.4. Methods, the other specifications and type-checking times are on the [Benchmarks](https://orqc.7nohe.dev/guides/benchmarks/) page; the scripts are in [`benchmarks/`](./benchmarks).
+¹ Measured on 2026-11-13 on an Apple M2 with Node.js 24 (generation time is the median wall-clock time of the CLI), with 4.0.0-beta.4, `@hey-api/openapi-ts` 0.99.0, Orval 8.46.0 and openapi-typescript 7.13.0 + openapi-react-query 0.5.4. Methods, the other specifications and type-checking times are on the [Benchmarks](https://orqc.7nohe.dev/guides/benchmarks/) page; the scripts are in [`benchmarks/`](./benchmarks). The [Comparison](https://orqc.7nohe.dev/guides/comparison/) page covers Kubb too, and what each tool generates in more detail.
**Scope**: this library is deliberately React-focused — use the hey-api plugin if you need non-React frameworks. Its [MSW mocks](https://orqc.7nohe.dev/guides/mocking/) answer with fixed values taken from the spec and keep no state; use Orval if you want randomly generated mock data.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index a2bac145..8d29d4b6 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -61,13 +61,14 @@ export default defineConfig({
{
label: "Getting started and usage",
description:
- "install, first run, the generated layout, using the generated hooks and queryOptions factories, every CLI option, mock data and MSW handlers, CI checks and coding agents",
+ "install, first run, the generated layout, using the generated hooks and queryOptions factories, every CLI option, mock data and MSW handlers, CI checks, coding agents and the FAQ",
paths: [
"guides/introduction",
"guides/usage",
"guides/cli-options",
"guides/mocking",
"guides/ci-and-agents",
+ "guides/faq",
],
},
{
@@ -83,10 +84,10 @@ export default defineConfig({
paths: ["guides/migrating-*"],
},
{
- label: "Benchmarks",
+ label: "Comparison and benchmarks",
description:
- "generation time, install size and type errors compared with other generators, and what a coding agent spends",
- paths: ["guides/benchmarks"],
+ "what Orval, Kubb, Hey API and openapi-react-query generate compared with this library, with generation time, install size and type errors, and what a coding agent spends",
+ paths: ["guides/comparison", "guides/benchmarks"],
},
],
promote: [
@@ -96,6 +97,8 @@ export default defineConfig({
"guides/cli-options",
"guides/mocking",
"guides/ci-and-agents",
+ "guides/faq",
+ "guides/comparison",
],
demote: ["guides/migrating-to-v3", "contributing", "license"],
exclude: ["guides/migrating-to-v3", "contributing", "license"],
@@ -137,7 +140,9 @@ export default defineConfig({
{ slug: "guides/cli-options" },
{ slug: "guides/mocking" },
{ slug: "guides/ci-and-agents" },
+ { slug: "guides/comparison" },
{ slug: "guides/benchmarks" },
+ { slug: "guides/faq" },
{ slug: "guides/migrating-to-v3" },
{ slug: "guides/migrating-to-v4" },
{ slug: "guides/migrating-from-openapi-react-query" },
diff --git a/docs/src/content/docs/examples/nextjs.md b/docs/src/content/docs/examples/nextjs.md
index e26529cd..4554739f 100644
--- a/docs/src/content/docs/examples/nextjs.md
+++ b/docs/src/content/docs/examples/nextjs.md
@@ -3,4 +3,194 @@ title: Next.js Example
description: A Next.js App Router example that prefetches on the server and hydrates TanStack Query hooks generated from an OpenAPI document.
---
-Example of using Next.js can be found in the [`examples/nextjs-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/nextjs-app) directory of the repository.
+Example of using Next.js can be found in the [`examples/nextjs-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/nextjs-app) directory of the repository. It uses the App Router: a Server Component prefetches a query, and a Client Component reads the same data through the generated hook without fetching it again.
+
+## Generate the code
+
+```json
+{ "scripts": { "codegen": "orqc -i ./petstore.yaml" } }
+```
+
+The command writes the client to `openapi/requests/` and the TanStack Query code to `openapi/queries/`. The default client uses `fetch`, which is what the server needs too.
+
+## Configure the client and the provider
+
+Set the base URL in one module:
+
+```ts
+// fetchClient.ts
+import { client } from "@/openapi/requests/client.gen";
+
+client.setConfig({
+ baseUrl: "http://localhost:4010",
+});
+```
+
+Next.js bundles Server Components and Client Components separately, so each side has its own copy of the generated client. Import this module on both: in the provider below for the browser, and in every Server Component that prefetches. A Server Component that leaves it out sends its request to the server URL written in the specification.
+
+The `QueryClientProvider` needs a Client Component. Create one `QueryClient` per request on the server and keep a single one in the browser:
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import "../fetchClient";
+
+function makeQueryClient() {
+ return new QueryClient({
+ defaultOptions: {
+ queries: {
+ // Above 0, so the browser does not refetch what the server just sent.
+ staleTime: 60 * 1000,
+ },
+ },
+ });
+}
+
+let browserQueryClient: QueryClient | undefined;
+
+function getQueryClient() {
+ if (typeof window === "undefined") return makeQueryClient();
+ if (!browserQueryClient) browserQueryClient = makeQueryClient();
+ return browserQueryClient;
+}
+
+export default function Providers({ children }: { children: React.ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+Wrap the application with it in `app/layout.tsx`.
+
+## Prefetch in a Server Component
+
+Every GET operation has a prefetch function in `openapi/queries/prefetch`. Call it in a Server Component, then pass the cache to the browser with `HydrationBoundary`:
+
+```tsx
+// app/page.tsx
+import {
+ dehydrate,
+ HydrationBoundary,
+ QueryClient,
+} from "@tanstack/react-query";
+import "../fetchClient";
+import { prefetchUseFindPets } from "../openapi/queries/prefetch";
+import Pets from "./components/Pets";
+
+export default async function Home() {
+ const queryClient = new QueryClient();
+
+ await prefetchUseFindPets(queryClient, {
+ query: { tags: [], limit: 10 },
+ });
+
+ return (
+
+
+
+ );
+}
+```
+
+## Read the data in a Client Component
+
+```tsx
+// app/components/Pets.tsx
+"use client";
+
+import { useFindPets } from "@/openapi/queries";
+
+export default function Pets() {
+ const { data } = useFindPets({
+ query: { tags: [], limit: 10 },
+ });
+
+ return (
+
+ {data?.map((pet) => (
+
{pet.name}
+ ))}
+
+ );
+}
+```
+
+Pass the hook the same options as the prefetch function, and no query key of your own as its second argument. The query key is the operation's key followed by the options, and a key of your own takes the place of the options. Either difference is a different cache entry, and the browser fetches again.
+
+## Infinite queries
+
+A paginated operation also gets a prefetch function for its first page. The Client Component continues from there with `fetchNextPage`:
+
+```tsx
+// app/infinite-loader/page.tsx
+import {
+ dehydrate,
+ HydrationBoundary,
+ QueryClient,
+} from "@tanstack/react-query";
+import "../../fetchClient";
+import { prefetchUseFindPaginatedPetsInfinite } from "../../openapi/queries/prefetch";
+import PaginatedPets from "../components/PaginatedPets";
+
+export default async function InfiniteLoaderPage() {
+ const queryClient = new QueryClient();
+
+ await prefetchUseFindPaginatedPetsInfinite(queryClient, {
+ query: { limit: 10, tags: [] },
+ });
+
+ return (
+
+
+
+ );
+}
+```
+
+```tsx
+// app/components/PaginatedPets.tsx
+"use client";
+
+import { useFindPaginatedPetsInfinite } from "@/openapi/queries/infiniteQueries";
+
+export default function PaginatedPets() {
+ const { data, fetchNextPage } = useFindPaginatedPetsInfinite({
+ query: { limit: 10, tags: [] },
+ });
+
+ return (
+ <>
+
+ {data?.pages.at(-1)?.nextPage && (
+
+ )}
+ >
+ );
+}
+```
+
+An operation is paginated when it has the query parameter named by [`--pageParam`](/guides/cli-options/#--pageparam-value). See [Usage](/guides/usage/#using-the-generated-useinfinitequery-hooks) for the details.
+
+## Run the example
+
+From the root of the repository:
+
+```bash
+pnpm install
+pnpm build
+pnpm --filter nextjs-app generate:api
+pnpm --filter nextjs-app dev
+```
+
+`dev` starts Next.js and a small mock Petstore server on `http://localhost:4010`.
diff --git a/docs/src/content/docs/examples/react-router.md b/docs/src/content/docs/examples/react-router.md
index cf4584e0..1e80b3bd 100644
--- a/docs/src/content/docs/examples/react-router.md
+++ b/docs/src/content/docs/examples/react-router.md
@@ -3,6 +3,143 @@ title: React Router Example
description: A React Router 8 (framework mode) example that loads data with TanStack Query code generated from an OpenAPI document.
---
-Example of using React Router 8 in framework mode can be found in the [`examples/react-router-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/react-router-app) directory of the repository.
+Example of using React Router 8 in framework mode can be found in the [`examples/react-router-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/react-router-app) directory of the repository. A route `loader` prefetches a query on the server, and the route component reads the same data through the generated hook.
React Router 8 needs Node.js 22.22 or later and React 19.2.7 or later. Import everything from `react-router`: `react-router-dom` has no v8.
+
+## Generate the code
+
+```json
+{ "scripts": { "codegen": "orqc -i ./petstore.yaml" } }
+```
+
+## Configure the client and the provider
+
+```ts
+// fetchClient.ts
+import { client } from "./openapi/requests/client.gen";
+
+client.setConfig({
+ baseUrl: "http://localhost:4010",
+ throwOnError: true,
+});
+```
+
+```tsx
+// providers.tsx
+import "./fetchClient";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import React from "react";
+
+export default function Providers({ children }: { children: React.ReactNode }) {
+ const [queryClient] = React.useState(
+ () =>
+ new QueryClient({
+ defaultOptions: {
+ queries: {
+ // Above 0, so the browser does not refetch what the server just sent.
+ staleTime: 30 * 1000,
+ },
+ },
+ }),
+ );
+
+ return (
+ {children}
+ );
+}
+```
+
+Wrap `` with it in `app/root.tsx`.
+
+## Prefetch in the loader
+
+Call the generated prefetch function in the route's `loader` and return the dehydrated cache. The component hands it to `HydrationBoundary`:
+
+```tsx
+// app/routes/_index/route.tsx
+import {
+ dehydrate,
+ HydrationBoundary,
+ QueryClient,
+} from "@tanstack/react-query";
+import { useFindPets } from "../../../openapi/queries";
+import { prefetchUseFindPets } from "../../../openapi/queries/prefetch";
+import type { Route } from "./+types/route";
+
+export async function loader(_: Route.LoaderArgs) {
+ const queryClient = new QueryClient();
+
+ await prefetchUseFindPets(queryClient, {
+ query: { tags: [], limit: 10 },
+ });
+
+ return { dehydratedState: dehydrate(queryClient) };
+}
+
+function Pets() {
+ const { data } = useFindPets({ query: { tags: [], limit: 10 } });
+
+ return (
+
+ {data?.map((pet) => (
+
{pet.name}
+ ))}
+
+ );
+}
+
+export default function Index({ loaderData }: Route.ComponentProps) {
+ return (
+
+
+
+ );
+}
+```
+
+Pass the hook the same options as the prefetch function, and no query key of your own as its second argument. The query key is the operation's key followed by the options, and a key of your own takes the place of the options. Either difference is a different cache entry, and the browser fetches again.
+
+## Mutation and invalidation
+
+```tsx
+import { useQueryClient } from "@tanstack/react-query";
+import { UseFindPetsKeyFn, useAddPet } from "../../../openapi/queries";
+
+function AddPet({ name }: { name: string }) {
+ const queryClient = useQueryClient();
+ const { mutate: addPet } = useAddPet();
+
+ return (
+
+ );
+}
+```
+
+## Run the example
+
+From the root of the repository:
+
+```bash
+pnpm install
+pnpm build
+pnpm --filter @7nohe/react-router-app generate:api
+pnpm --filter @7nohe/react-router-app dev
+```
+
+`dev` starts React Router and a small mock Petstore server on `http://localhost:4010`.
diff --git a/docs/src/content/docs/examples/vite-react.md b/docs/src/content/docs/examples/vite-react.md
index 0c7c3c93..ecefd141 100644
--- a/docs/src/content/docs/examples/vite-react.md
+++ b/docs/src/content/docs/examples/vite-react.md
@@ -3,4 +3,153 @@ title: Vite + React Example
description: A Vite + React example app that calls an API through TanStack Query hooks generated from an OpenAPI document.
---
-Example of using Vite with React can be found in the [`examples/react-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/react-app) directory of the repository.
+Example of using Vite with React can be found in the [`examples/react-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/react-app) directory of the repository. It is a single-page app on the axios client that reads a list, adds to it with a mutation and shows a suspense query.
+
+## Generate the code
+
+```json
+{ "scripts": { "codegen": "orqc -i ./petstore.yaml -c axios" } }
+```
+
+`-c axios` generates the client on axios, so install `axios` in the project. Without the flag the client uses `fetch` and needs no package.
+
+## Configure the client and the provider
+
+```ts
+// src/axios.ts
+import { client } from "../openapi/requests/client.gen";
+
+client.setConfig({
+ baseURL: "http://localhost:4010",
+});
+```
+
+The axios client takes `baseURL`, as axios does. The fetch client takes `baseUrl`.
+
+```tsx
+// src/main.tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import App from "./App";
+import "./axios";
+
+export const queryClient = new QueryClient();
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+
+
+
+
+ ,
+);
+```
+
+## Query
+
+```tsx
+import { useFindPets } from "../openapi/queries";
+
+function Pets() {
+ const { data, error, refetch } = useFindPets({
+ query: { tags: [], limit: 10 },
+ });
+
+ if (error)
+ return (
+
+ );
+
+ return (
+
+ {data?.map((pet) => (
+
{pet.name}
+ ))}
+
+ );
+}
+```
+
+When every parameter of an operation is optional, the hook can be called with no argument: `useFindPets()`.
+
+## Mutation and invalidation
+
+A mutation hook takes the request as the variables of `mutate`. After it succeeds, invalidate the list with the key function of the query, called with the same options the query was called with:
+
+```tsx
+import { useQueryClient } from "@tanstack/react-query";
+import { UseFindPetsKeyFn, useAddPet } from "../openapi/queries";
+
+function AddPet({ name }: { name: string }) {
+ const queryClient = useQueryClient();
+ const { mutate: addPet, isPending } = useAddPet();
+
+ return (
+
+ );
+}
+```
+
+To cancel a mutation, pass an `AbortSignal` next to the body: `addPet({ body, signal: controller.signal })`.
+
+## Suspense
+
+The suspense hooks are in `openapi/queries/suspense`. `data` is never `undefined` there. An error is thrown to the nearest error boundary when there is no data to show; if a refetch fails while data is cached, the component keeps rendering that data:
+
+```tsx
+import { Suspense } from "react";
+import { useFindPetsSuspense } from "../openapi/queries/suspense";
+
+function PetList() {
+ const { data } = useFindPetsSuspense({ query: { tags: [], limit: 10 } });
+
+ return (
+
+ {data.map((pet) => (
+
{pet.name}
+ ))}
+
+ );
+}
+
+export function Pets() {
+ return (
+ loading...>}>
+
+
+ );
+}
+```
+
+## Run the example
+
+From the root of the repository:
+
+```bash
+pnpm install
+pnpm build
+pnpm --filter @7nohe/react-app generate:api
+pnpm --filter @7nohe/react-app dev
+```
+
+`dev` starts Vite and a small mock Petstore server on `http://localhost:4010`.
diff --git a/docs/src/content/docs/guides/comparison.mdx b/docs/src/content/docs/guides/comparison.mdx
new file mode 100644
index 00000000..c39c752b
--- /dev/null
+++ b/docs/src/content/docs/guides/comparison.mdx
@@ -0,0 +1,124 @@
+---
+title: Comparison
+description: Why choose OpenAPI React Query Codegen over Orval, Kubb, Hey API or openapi-react-query. Generation time, install size and type errors measured, what each tool generates for TanStack Query, and when another tool fits better.
+---
+
+import {
+ addedPackages,
+ generationSeconds,
+ operations,
+ tools,
+ typeErrors,
+} from "../../../data/benchmarks";
+
+export const pick = (rows, id) =>
+ rows[tools.findIndex((tool) => tool.id === id)].value;
+export const others = (rows) => rows.slice(1).map((row) => row.value);
+export const seconds = generationSeconds("github");
+export const githubOperations = operations("github").toLocaleString("en-US");
+
+Orval, Kubb, Hey API and openapi-react-query also turn an OpenAPI document into code for TanStack Query. This library is the one built only for React and TanStack Query v5, and that focus is where its advantages come from.
+
+## What sets it apart
+
+- **Everything is generated, with nothing to configure.** One command writes a hook, a suspense hook, a `queryOptions` factory, a prefetch function, an `ensureQueryData` function and a key function for every GET operation, and a mutation hook for the rest. With Orval and Kubb several of these are options you turn on. Hey API, and Kubb by default, generate options factories that you wire to the hooks yourself.
+- **It is the fastest on every specification we measured.** The GitHub REST API ({githubOperations} operations) takes {seconds[0].value.toFixed(2)} seconds. The other four take between {Math.min(...others(seconds)).toFixed(2)} and {Math.max(...others(seconds)).toFixed(2)} seconds.
+- **It installs the least.** The generator adds {addedPackages[0].value} packages to a project. The others add between {Math.min(...others(addedPackages))} and {Math.max(...others(addedPackages))}.
+- **Its output compiles.** For the Stripe and GitHub APIs, `tsc` with `strict` reports no error in the generated code. That is not true of every generator: see the table below.
+- **Server rendering is covered.** It is the only tool here that generates `ensureQueryData` functions, and prefetch functions come without an option. There are examples for [Next.js](/examples/nextjs/), [React Router](/examples/react-router/) and [TanStack Router](/examples/tanstack-router/).
+- **It is made for CI and for coding agents.** [`--check`](/guides/ci-and-agents/) fails the build when the committed output is out of date, `--json` prints errors as JSON, and [`--agentsMd`](/guides/ci-and-agents/#coding-agents-a-guide-in-your-agentsmd) keeps a guide in your `AGENTS.md` that cut what an agent had to read by a quarter to a third in our runs.
+- **The output is stable.** The client and the hooks come from one package and change in a breaking way only in a major version, with a migration guide.
+
+## Measured
+
+
+
+
+
Tool
+
Generation time, GitHub REST API ({githubOperations} operations)
+
+How these were measured, the versions and the other specifications are on the [Benchmarks](/guides/benchmarks/) page. The scripts are in the repository, so you can run them yourself.
+
+## Feature by feature
+
+| | This library | Orval | Kubb | Hey API | openapi-react-query |
+|---|---|---|---|---|---|
+| Hooks per operation | Yes, always | Yes | With `hooks: true` | Not in the documented output | No generated code: `$api.useQuery("get", "/pets")` |
+| Suspense hooks | Yes, always | With `useSuspenseQuery` | With `suspense` | No | `$api.useSuspenseQuery` |
+| Prefetch functions | Yes, always | With `usePrefetch` | No | No | No |
+| `ensureQueryData` functions | Yes, always | No | No | No | No |
+| `queryOptions` factories | Yes | Yes (`getXxxQueryOptions`) | Yes, the default output | Yes, the default output | `$api.queryOptions(...)` |
+| Query key functions | Yes | Yes | Yes | Yes | No, the key is `[method, path, params]` |
+| Infinite queries | Found by the `--pageParam` query parameter | `useInfinite` and `useInfiniteQueryParam` | `infinite` option | Found by pagination keywords | At the call site |
+| Check for stale output in CI | `--check` | `--outdated` | `--dry-run` shows planned changes | No | `--check` |
+| Errors as JSON | `--json` | No | `--reporter json` | No | No |
+| Release line | SemVer, v4 in beta | v8 | v5 | Before 1.0 | Maintenance mode |
+| Configuration | Command line flags | `orval.config.ts` | `kubb.config.ts` | `openapi-ts.config.ts` | Command line flags |
+| HTTP client | fetch or axios, generated into the output | fetch, axios or your own | fetch, axios or your own | Fetch, Axios, Ky, OFetch and others | fetch, through the `openapi-fetch` package |
+| Frameworks | React | React, Vue, Svelte, Solid, Angular | React, Vue | React, Vue, Svelte, Solid, Angular, Preact | React |
+| Other data libraries | No | SWR, Pinia Colada | SWR | Pinia Colada | No |
+| Schema validation | JSON Schema constants | Zod, Valibot, Effect | Zod | Zod, Valibot | No |
+| Mocks | MSW handlers with fixed values | MSW and Faker | MSW and Faker | In progress | No |
+
+Where a tool has no helper of its own, such as prefetching with Kubb or Hey API, you pass its `queryOptions` factory to `queryClient.prefetchQuery` or `queryClient.ensureQueryData` yourself.
+
+The table was checked on 2026-11-15 against the documentation of Orval 8.48.0, Kubb 5.20.1 with `@kubb/plugin-react-query` 5.10.3, `@hey-api/openapi-ts` 0.99.0, and openapi-typescript 7.13.0 with openapi-react-query 0.5.4. If something is out of date, please [open an issue](https://github.com/7nohe/openapi-react-query-codegen/issues).
+
+## Compared with Orval
+
+Choose this library when you want React and TanStack Query without a configuration file. Suspense hooks, prefetch functions and `ensureQueryData` functions are there for every operation, where [Orval](https://orval.dev) has an option for each of the first two and none for the third. The generator adds {addedPackages[0].value} packages where Orval adds {pick(addedPackages, "orval")}, generates the GitHub API in {seconds[0].value.toFixed(2)} seconds where Orval takes {pick(seconds, "orval").toFixed(2)}, and its output for the Stripe API compiles where Orval's had {pick(typeErrors("stripe"), "orval")} type errors in our run.
+
+Choose Orval when you need Vue, Svelte, Solid or Angular, SWR, Zod or Valibot schemas, mock data that is random, or per-operation overrides in a configuration file.
+
+## Compared with Kubb
+
+Choose this library when the fixed output is what you want. [Kubb](https://kubb.dev) is a plugin system: its React Query plugin generates `queryOptions` and `mutationOptions` factories by default and hooks when you set `hooks: true`, and you compose the rest in `kubb.config.ts` from plugins for the types, the client and the queries. Here there is one command and one package, {addedPackages[0].value} packages installed where that Kubb setup adds {pick(addedPackages, "kubb")}, and prefetch and `ensureQueryData` functions that Kubb does not generate.
+
+Choose Kubb when you want to compose the output from plugins, write your own, or generate Vue Query, SWR or Zod code from the same configuration.
+
+## Compared with Hey API
+
+Choose this library when you want ready-made hooks. The documented output of the TanStack Query plugin of [Hey API](https://heyapi.dev) (`@hey-api/openapi-ts`) is options factories and query keys, which you pass to `useQuery`, `useInfiniteQuery` and `useMutation` yourself. It has no suspense, prefetch or `ensureQueryData` helpers. Hey API is before 1.0 and asks you to pin an exact version, while this library changes its output in a breaking way only in a major version. In our run, the output of 0.99.0 for the Stripe API had {pick(typeErrors("stripe"), "hey-api")} type errors, and that version did not run in a project with TypeScript 7.
+
+Up to v3 this library used `@hey-api/openapi-ts` to generate its client. Since v4 it has its own generator, which removed most of the packages it used to install. See [Migrating to v4](/guides/migrating-to-v4/).
+
+Choose Hey API when you need a framework other than React, an HTTP client other than fetch and axios, or Zod or Valibot validation.
+
+## Compared with openapi-typescript and openapi-react-query
+
+Choose this library when you want a project that is maintained. [openapi-typescript](https://openapi-ts.dev) announced that it is [in maintenance mode](https://github.com/openapi-ts/openapi-typescript/issues/2874) from September 2026 and will get no more updates, and `openapi-fetch` and `openapi-react-query` with it. [Migrating from openapi-react-query](/guides/migrating-from-openapi-react-query/) shows the move step by step.
+
+The approach differs too. openapi-typescript generates types only, and you call `$api.useQuery("get", "/pets/{petId}", ...)` with the method and the path as strings. Here every operation is a named hook (`useFindPetById`) that an editor can complete and a search can find, with key functions for invalidation and prefetch functions for the server, and no runtime package between your code and `fetch`.
+
+That approach keeps very little generated code in the repository, which is its appeal. If that matters more to you than named hooks, it still works with the versions that exist today.
+
+## When another tool fits better
+
+This library is deliberately narrow. Another tool is the better choice when:
+
+- You use Vue, Svelte, Solid or Angular. The hooks are for React.
+- You want Zod or Valibot schemas generated for runtime validation. This library writes JSON Schema constants only.
+- You want mock data that is random, or mocks that keep state. The generated MSW handlers answer with fixed values from the specification.
+- You need an HTTP client other than fetch or axios.
+- You want to change the shape of the generated code. There are flags, but no templates or plugins.
+
+## In short
+
+For a React application on TanStack Query v5, this library gives you the most generated code for the least setup: typed hooks and server-side helpers for every operation from one command, the smallest install and the fastest generation of the tools compared here, and output that compiles. Reach for one of the others when you need what it leaves out: another framework, runtime validation or a plugin system.
diff --git a/docs/src/content/docs/guides/faq.md b/docs/src/content/docs/guides/faq.md
new file mode 100644
index 00000000..ec82f8f5
--- /dev/null
+++ b/docs/src/content/docs/guides/faq.md
@@ -0,0 +1,121 @@
+---
+title: FAQ
+description: Short answers about OpenAPI React Query Codegen. Supported OpenAPI and TanStack Query versions, fetch or axios, authentication, errors, infinite queries, SSR, mocks, CI and how v4 differs from v3.
+---
+
+## Getting started
+
+### What does OpenAPI React Query Codegen generate?
+
+It reads an OpenAPI document and writes two directories. `openapi/requests/` is a typed HTTP client: one function per operation, the request and response types, and a small fetch or axios runtime. `openapi/queries/` is TanStack Query (React Query) v5 code on top of it: for every GET operation a `useQuery` hook, a suspense hook, a `queryOptions` factory, a prefetch function, an `ensureQueryData` function and a query key function, and for every other operation a `useMutation` hook. See [Introduction](/guides/introduction/).
+
+### Which package do I install?
+
+`@7nohe/openapi-react-query-codegen`. Its command is `orqc` (`openapi-rq` also works). The same package is published as `@7nohe/orqc` so that `npx @7nohe/orqc@beta -i ./openapi.yaml` is short to type. The unscoped `openapi-react-query-codegen` and `openapi-rq` packages on npm, and copies under other scopes, are not published by this project.
+
+### Is v4 stable?
+
+v4 is in beta. `npm install -D @7nohe/openapi-react-query-codegen@beta` installs it; without `@beta` npm installs v3. This site describes v4. The v3 documentation is in the [`v3` branch](https://github.com/7nohe/openapi-react-query-codegen/tree/v3) of the repository, and [Migrating to v4](/guides/migrating-to-v4/) lists what changes.
+
+### What does it require?
+
+Node.js 24 or later to run the generator, and `@tanstack/react-query` 5 in the project. The generated code compiles with TypeScript 5, 6 and 7 and has no Node.js requirement of its own.
+
+### Does it work with Vue, Svelte, Solid or Angular?
+
+No. The generated hooks are for React. For another framework, see [Comparison](/guides/comparison/).
+
+## The specification
+
+### Which OpenAPI versions are supported?
+
+OpenAPI 3.0 and 3.1, in YAML or JSON, including external `$ref`s to files and URLs. Swagger/OpenAPI 2.0 documents are rejected with an error: convert them to OpenAPI 3 first.
+
+### Can the input be a URL?
+
+Yes. `-i` takes a file path or an `http(s)` URL.
+
+### What if my operations have no `operationId`?
+
+They are named after the method and the path, such as `getPetsById`. `--noOperationId` names every operation that way.
+
+## The generated code
+
+### Should I commit the generated code?
+
+That is the project's choice. If you commit it, run the generator with [`--check`](/guides/ci-and-agents/) in CI, so that a change to the specification cannot be merged without regenerating.
+
+### Can I edit the generated files?
+
+No. The next run overwrites them. Change the specification or the flags and regenerate. To change how one request is made, configure the client or pass options to the hook.
+
+### Does the generated code need a runtime package?
+
+Only `@tanstack/react-query`, and `axios` if you generate with `-c axios`. The fetch runtime is written into `openapi/requests/runtime.gen.ts`, and nothing in the output imports this package.
+
+### Should I use fetch or axios?
+
+`fetch` is the default and needs no package. Choose `-c axios` when the project already configures axios (instances, interceptors, adapters) and you want the generated client to use it.
+
+### How do I set the base URL and send a token?
+
+Configure the generated client once, before the first request:
+
+```ts
+import { client } from "./openapi/requests/client.gen";
+
+client.setConfig({
+ baseUrl: "https://api.example.com",
+ // Sent with every operation that declares `security` in the specification.
+ auth: () => localStorage.getItem("token") ?? undefined,
+});
+```
+
+For a header on every request, whatever the specification says, add a request interceptor:
+
+```ts
+client.interceptors.request.use((request) => {
+ request.headers.set("X-Tenant", "acme");
+ return request;
+});
+```
+
+With the axios client the option is `baseURL`, and interceptors are registered on the axios instance: `client.instance.interceptors.request.use(...)`.
+
+### How are error responses handled?
+
+The generated hooks reject on an error response, so `error` and `isError` are set on queries and `onError` runs on mutations, with the error typed from the responses the specification declares.
+
+### How do infinite queries get generated?
+
+A GET operation gets `useXxxInfinite` when it has a query parameter with the name given by `--pageParam` (default `page`). `--nextPageParam` (default `nextPage`, dot notation for nested values) is the response property the generated `getNextPageParam` reads; when your API signals the next page differently, pass your own `getNextPageParam` to the hook. See [Usage](/guides/usage/#using-the-generated-useinfinitequery-hooks).
+
+### Does it work with Next.js App Router and other SSR frameworks?
+
+Yes. Prefetch on the server with the generated `prefetchUseXxx` or `ensureUseXxxData` functions and hydrate on the client. There are examples for [Next.js](/examples/nextjs/), [React Router](/examples/react-router/) and [TanStack Router](/examples/tanstack-router/).
+
+### Does it generate Zod schemas?
+
+No. It writes the schemas of the specification as JSON Schema constants to `openapi/requests/schemas.gen.ts` (turn that off with `--noSchemas`), which form and validation libraries that accept JSON Schema can use.
+
+### Can it generate mock data?
+
+Yes. `--mock msw` writes mock data and [MSW](https://mswjs.io) request handlers for every operation. The values are fixed and taken from the specification. See [Mocking with MSW](/guides/mocking/).
+
+## Workflow
+
+### How do I keep the generated code up to date in CI?
+
+Run the same command with `--check`. It generates into a temporary directory, changes nothing, and exits with `1` when the committed output differs. `--json` prints errors as one line of JSON. See [CI and Coding Agents](/guides/ci-and-agents/).
+
+### How do I use it with a coding agent?
+
+Add `--agentsMd` to the command. It keeps a short block in the project's `AGENTS.md` (or the file you name) that tells the agent how to find one operation with `grep` instead of reading the generated files. The package also ships its own `AGENTS.md`, and this site serves [`llms.txt`](/llms.txt). See [CI and Coding Agents](/guides/ci-and-agents/#coding-agents-agentsmd-and-llmstxt).
+
+### How does it relate to `@hey-api/openapi-ts`?
+
+Up to v3 the client in `openapi/requests/` was produced by `@hey-api/openapi-ts` and this package generated the hooks on top. Since v4 the client generator is part of this package, and `@hey-api/openapi-ts` is no longer a dependency. The hooks keep their names and signatures. See [Migrating to v4](/guides/migrating-to-v4/).
+
+### How does it compare with Orval, Kubb, Hey API and openapi-react-query?
+
+See [Comparison](/guides/comparison/) for what each generates, and [Benchmarks](/guides/benchmarks/) for generation time, install size and type errors in the output.
diff --git a/docs/src/content/docs/guides/migrating-to-v4.mdx b/docs/src/content/docs/guides/migrating-to-v4.mdx
index fb868656..fbe9c4c0 100644
--- a/docs/src/content/docs/guides/migrating-to-v4.mdx
+++ b/docs/src/content/docs/guides/migrating-to-v4.mdx
@@ -124,7 +124,7 @@ The constants have the names v3 gave them (`PetSchema`, `my_schemaSchema`, `PetW
## Dependency changes
- Node.js 24 or later is required (`engines.node` is `>=24.0.0`; v3 needed 22.18). This is the version that runs `orqc`. The generated code has no Node.js requirement of its own.
-- `@hey-api/openapi-ts` is no longer a dependency, so its (FSL) license no longer applies to your install.
+- `@hey-api/openapi-ts` is no longer a dependency.
- `yaml` (exact-pinned, no dependencies of its own) was added to parse YAML specifications.
- `typescript` is no longer a peer dependency, so the TypeScript version of your project cannot conflict with this package, and TypeScript 7 works. The generator reads your `tsconfig.json` itself (comments, trailing commas and `extends` included) to decide whether relative imports need `.js`, instead of using the TypeScript compiler API, which version 7 does not have. The generated code compiles with TypeScript 5.x, 6.x and 7.x.
- `ts-morph` is no longer a peer dependency. If you installed it only for this package, you can remove it. The hook files are now printed directly, which makes generation faster on large specifications.
diff --git a/docs/src/content/docs/guides/usage.mdx b/docs/src/content/docs/guides/usage.mdx
index 0a7ff9d6..bcd83f51 100644
--- a/docs/src/content/docs/guides/usage.mdx
+++ b/docs/src/content/docs/guides/usage.mdx
@@ -213,7 +213,7 @@ export default App;
## Using the generated `useInfiniteQuery` hooks
-This feature will generate a function in infiniteQueries.ts when the name specified by the `pageParam` option exists in the query parameters and the name specified by the `nextPageParam` option exists in the response.
+This feature will generate a function in infiniteQueries.ts when the name specified by the `pageParam` option exists in the query parameters of a GET operation. The generated `getNextPageParam` reads the next page from the response property named by the `nextPageParam` option.
The `initialPageParam` option can be specified to set the intial page to load, defaults to 1. The `nextPageParam` supports dot notation for nested values (i.e. `meta.next`).
diff --git a/examples/nextjs-app/app/infinite-loader/page.tsx b/examples/nextjs-app/app/infinite-loader/page.tsx
index 31deaf57..d8e356e4 100644
--- a/examples/nextjs-app/app/infinite-loader/page.tsx
+++ b/examples/nextjs-app/app/infinite-loader/page.tsx
@@ -3,6 +3,7 @@ import {
HydrationBoundary,
QueryClient,
} from "@tanstack/react-query";
+import "../../fetchClient";
import { prefetchUseFindPaginatedPetsInfinite } from "../../openapi/queries/prefetch";
import PaginatedPets from "../components/PaginatedPets";
diff --git a/examples/nextjs-app/app/page.tsx b/examples/nextjs-app/app/page.tsx
index 445c892e..426f0001 100644
--- a/examples/nextjs-app/app/page.tsx
+++ b/examples/nextjs-app/app/page.tsx
@@ -4,6 +4,7 @@ import {
QueryClient,
} from "@tanstack/react-query";
import Link from "next/link";
+import "../fetchClient";
import { prefetchUseFindPets } from "../openapi/queries/prefetch";
import Pets from "./components/Pets";