From 69cb36e448878961329c4798a31571ec80eadfff Mon Sep 17 00:00:00 2001
From: Urata Daiki <7nohe@users.noreply.github.com>
Date: Sun, 15 Nov 2026 11:14:21 +0900
Subject: [PATCH 1/5] docs: add a comparison page and an FAQ, and write out
three examples
- Comparison: what Orval, Kubb, Hey API and openapi-react-query generate
for TanStack Query next to this library, checked against their
documentation on 2026-11-15, with the benchmark numbers read from the
result files and a section on when this library is the wrong choice.
- FAQ: short answers to what people ask before installing (versions,
fetch or axios, tokens, errors, infinite queries, SSR, mocks, CI).
- The Next.js, Vite + React and React Router example pages were one
sentence and a link. They now show the code that matters in each
example. The snippets were type-checked inside the example apps.
- README: Orval does generate queryOptions factories
(getXxxQueryOptions), so the comparison table no longer says it does
not, and it links to the new page.
Both pages join the sidebar and the llms.txt sets.
---
README.md | 4 +-
docs/astro.config.mjs | 13 +-
docs/src/content/docs/examples/nextjs.md | 188 +++++++++++++++++-
.../src/content/docs/examples/react-router.md | 139 ++++++++++++-
docs/src/content/docs/examples/vite-react.md | 151 +++++++++++++-
docs/src/content/docs/guides/comparison.mdx | 98 +++++++++
docs/src/content/docs/guides/faq.md | 121 +++++++++++
7 files changed, 705 insertions(+), 9 deletions(-)
create mode 100644 docs/src/content/docs/guides/comparison.mdx
create mode 100644 docs/src/content/docs/guides/faq.md
diff --git a/README.md b/README.md
index 950f5bc..3ed1c6d 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 a2bac14..8d29d4b 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 e26529c..126f59f 100644
--- a/docs/src/content/docs/examples/nextjs.md
+++ b/docs/src/content/docs/examples/nextjs.md
@@ -3,4 +3,190 @@ 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 once, in a module that both the server and the browser load:
+
+```ts
+// fetchClient.ts
+import { client } from "@/openapi/requests/client.gen";
+
+client.setConfig({
+ baseUrl: "http://localhost:4010",
+});
+```
+
+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 { 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. The query key is built from them, so different options are 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 { 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 && (
+
+ )}
+ >
+ );
+}
+```
+
+Which operations count as paginated is decided by [`--pageParam` and `--nextPageParam`](/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 cf4584e..8a6953f 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. The query key is built from them, so different options are 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 0c7c3c9..9fc1cd1 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, and an error is thrown to the nearest error boundary:
+
+```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 0000000..b2cea33
--- /dev/null
+++ b/docs/src/content/docs/guides/comparison.mdx
@@ -0,0 +1,98 @@
+---
+title: Comparison
+description: How OpenAPI React Query Codegen differs from Orval, Kubb, Hey API and openapi-react-query in what they generate for TanStack Query, the frameworks and HTTP clients they support, and when to choose which.
+---
+
+import {
+ addedPackages,
+ generationSeconds,
+ operations,
+ tools,
+ typeErrors,
+} from "../../../data/benchmarks";
+
+Several tools turn an OpenAPI document into code for TanStack Query. They differ mostly in scope. This library does one thing: React and TanStack Query v5, from one command with no configuration file. The others are broader, and that is often the reason to choose them.
+
+This page 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 here is out of date, please [open an issue](https://github.com/7nohe/openapi-react-query-codegen/issues).
+
+## At a glance
+
+| | 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")` |
+| `queryOptions` factories | Yes | Yes (`getXxxQueryOptions`) | Yes, the default output | Yes, the default output | `$api.queryOptions(...)` |
+| Suspense hooks | Yes | With `useSuspenseQuery` | With `suspense` | No | `$api.useSuspenseQuery` |
+| Infinite queries | Found by `--pageParam` and `--nextPageParam` | `useInfinite` and `useInfiniteQueryParam` | `infinite` option | Found by pagination keywords | At the call site |
+| Prefetch and `ensureQueryData` functions | Yes, per operation | Prefetch with `usePrefetch` | No | No | No |
+| Query key functions | Yes | Yes | Yes | Yes | No, the key is `[method, path, params]` |
+| 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 |
+| 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 |
+| 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 |
+| Configuration | Command line flags | `orval.config.ts` | `kubb.config.ts` | `openapi-ts.config.ts` | Command line flags |
+| Check for stale output in CI | `--check` | `--outdated` | `--dry-run` shows planned changes | No | `--check` |
+| Errors as JSON | `--json` | No | `--reporter json` | No | 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.
+
+## Measured
+
+
+
+
+
Tool
+
Generation time, GitHub REST API ({operations("github").toLocaleString("en-US")} operations)
+
Packages added
+
Type errors in the output, Stripe / GitHub
+
+
+
+ {tools.map((tool, index) => (
+
+
{tool.name}
+
{generationSeconds("github")[index].value.toFixed(2)} s
+
+How these were measured, the versions and the other specifications are on the [Benchmarks](/guides/benchmarks/) page.
+
+## Orval
+
+[Orval](https://orval.dev) generates hooks per operation too, with `queryOptions` factories, key functions and optional suspense, infinite, prefetch and invalidation helpers. It covers far more than React: Vue, Svelte, Solid and Angular with TanStack Query, SWR, Pinia Colada, and Zod, Valibot or Effect schemas. Its mocks use MSW with Faker, so they return random data.
+
+Choose Orval when you need one of those targets, random mock data, or a configuration file with per-operation overrides. Choose this library when you want React and TanStack Query without configuration: suspense hooks, prefetch and `ensureQueryData` functions are generated for every operation with no option to turn on, the generator installs {addedPackages[0].value} packages, and it is faster on large specifications.
+
+## Kubb
+
+[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`. Other plugins add Vue Query, SWR, Zod, MSW and Faker, and you can write your own. It is configured in `kubb.config.ts`.
+
+Choose Kubb when you want to compose the output from plugins or generate something no fixed generator offers. Choose this library when the fixed output is what you want and you would rather not maintain a configuration.
+
+## Hey API
+
+[Hey API](https://heyapi.dev) (`@hey-api/openapi-ts`) is also plugin-based. Its TanStack Query plugin generates options factories and query keys that you pass to `useQuery`, `useInfiniteQuery` and `useMutation` yourself, for React, Vue, Svelte, Solid, Angular and Preact. It has the widest choice of HTTP clients here, and Zod and Valibot plugins. The project asks you to pin an exact version while it is before 1.0.
+
+Up to v3 this library used `@hey-api/openapi-ts` to generate its client. Since v4 it has its own generator, see [Migrating to v4](/guides/migrating-to-v4/).
+
+Choose Hey API when you need a framework other than React, another HTTP client, or runtime validation. Choose this library when you want ready-made hooks, suspense variants and server-side helpers per operation, and output that only changes in a breaking way between major versions.
+
+## openapi-typescript and openapi-react-query
+
+[openapi-typescript](https://openapi-ts.dev) generates types only. `openapi-fetch` and `openapi-react-query` are small runtime packages that use those types: you call `$api.useQuery("get", "/pets/{petId}", ...)` with the method and the path as strings, so there is nothing to regenerate except the types and very little code in your repository.
+
+The project 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. If you are moving on from it, see [Migrating from openapi-react-query](/guides/migrating-from-openapi-react-query/).
+
+## When this library is not the right choice
+
+- 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.
diff --git a/docs/src/content/docs/guides/faq.md b/docs/src/content/docs/guides/faq.md
new file mode 100644
index 0000000..a228aef
--- /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?
+
+An operation gets `useXxxInfinite` when it has a query parameter with the name given by `--pageParam` (default `page`) and its response has the property given by `--nextPageParam` (default `nextPage`, dot notation for nested values). 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.
From 3b454ba348de7a667086074f25fffff658a80fef Mon Sep 17 00:00:00 2001
From: Urata Daiki <7nohe@users.noreply.github.com>
Date: Sun, 15 Nov 2026 11:27:41 +0900
Subject: [PATCH 2/5] docs: address review of the examples, the FAQ and the
comparison
- Next.js: Server Components and Client Components are bundled apart, so
the client configured in the provider is not the one a Server
Component prefetches with. The page says so and imports fetchClient in
the Server Components. The example app had the same gap: its server
prefetch went to the URL in the specification, failed, and the browser
fetched instead. With the import the server HTML contains the pets.
- Infinite queries are generated from the --pageParam query parameter
alone; --nextPageParam only names what the default getNextPageParam
reads. Corrected in the FAQ, the comparison table and the usage guide.
- A query key passed to the hook makes it miss the prefetched entry.
- A suspense hook throws to the error boundary only when it has no data.
---
docs/src/content/docs/examples/nextjs.md | 10 +++++++---
docs/src/content/docs/examples/react-router.md | 2 +-
docs/src/content/docs/examples/vite-react.md | 2 +-
docs/src/content/docs/guides/comparison.mdx | 2 +-
docs/src/content/docs/guides/faq.md | 2 +-
docs/src/content/docs/guides/usage.mdx | 2 +-
examples/nextjs-app/app/infinite-loader/page.tsx | 1 +
examples/nextjs-app/app/page.tsx | 1 +
8 files changed, 14 insertions(+), 8 deletions(-)
diff --git a/docs/src/content/docs/examples/nextjs.md b/docs/src/content/docs/examples/nextjs.md
index 126f59f..d095404 100644
--- a/docs/src/content/docs/examples/nextjs.md
+++ b/docs/src/content/docs/examples/nextjs.md
@@ -15,7 +15,7 @@ The command writes the client to `openapi/requests/` and the TanStack Query code
## Configure the client and the provider
-Set the base URL once, in a module that both the server and the browser load:
+Set the base URL in one module:
```ts
// fetchClient.ts
@@ -26,6 +26,8 @@ client.setConfig({
});
```
+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
@@ -76,6 +78,7 @@ import {
HydrationBoundary,
QueryClient,
} from "@tanstack/react-query";
+import "../fetchClient";
import { prefetchUseFindPets } from "../openapi/queries/prefetch";
import Pets from "./components/Pets";
@@ -117,7 +120,7 @@ export default function Pets() {
}
```
-Pass the hook the same options as the prefetch function. The query key is built from them, so different options are a different cache entry and the browser fetches again.
+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 built from both, so anything different is a different cache entry and the browser fetches again.
## Infinite queries
@@ -130,6 +133,7 @@ import {
HydrationBoundary,
QueryClient,
} from "@tanstack/react-query";
+import "../../fetchClient";
import { prefetchUseFindPaginatedPetsInfinite } from "../../openapi/queries/prefetch";
import PaginatedPets from "../components/PaginatedPets";
@@ -176,7 +180,7 @@ export default function PaginatedPets() {
}
```
-Which operations count as paginated is decided by [`--pageParam` and `--nextPageParam`](/guides/cli-options/#--pageparam-value). See [Usage](/guides/usage/#using-the-generated-useinfinitequery-hooks) for the details.
+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
diff --git a/docs/src/content/docs/examples/react-router.md b/docs/src/content/docs/examples/react-router.md
index 8a6953f..e9c783b 100644
--- a/docs/src/content/docs/examples/react-router.md
+++ b/docs/src/content/docs/examples/react-router.md
@@ -98,7 +98,7 @@ export default function Index({ loaderData }: Route.ComponentProps) {
}
```
-Pass the hook the same options as the prefetch function. The query key is built from them, so different options are a different cache entry and the browser fetches again.
+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 built from both, so anything different is a different cache entry and the browser fetches again.
## Mutation and invalidation
diff --git a/docs/src/content/docs/examples/vite-react.md b/docs/src/content/docs/examples/vite-react.md
index 9fc1cd1..ecefd14 100644
--- a/docs/src/content/docs/examples/vite-react.md
+++ b/docs/src/content/docs/examples/vite-react.md
@@ -114,7 +114,7 @@ To cancel a mutation, pass an `AbortSignal` next to the body: `addPet({ body, si
## Suspense
-The suspense hooks are in `openapi/queries/suspense`. `data` is never `undefined` there, and an error is thrown to the nearest error boundary:
+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";
diff --git a/docs/src/content/docs/guides/comparison.mdx b/docs/src/content/docs/guides/comparison.mdx
index b2cea33..97d2eb0 100644
--- a/docs/src/content/docs/guides/comparison.mdx
+++ b/docs/src/content/docs/guides/comparison.mdx
@@ -22,7 +22,7 @@ This page was checked on 2026-11-15 against the documentation of Orval 8.48.0, K
| Hooks per operation | Yes, always | Yes | With `hooks: true` | Not in the documented output | No generated code: `$api.useQuery("get", "/pets")` |
| `queryOptions` factories | Yes | Yes (`getXxxQueryOptions`) | Yes, the default output | Yes, the default output | `$api.queryOptions(...)` |
| Suspense hooks | Yes | With `useSuspenseQuery` | With `suspense` | No | `$api.useSuspenseQuery` |
-| Infinite queries | Found by `--pageParam` and `--nextPageParam` | `useInfinite` and `useInfiniteQueryParam` | `infinite` option | Found by pagination keywords | At the call site |
+| Infinite queries | Found by the `--pageParam` query parameter | `useInfinite` and `useInfiniteQueryParam` | `infinite` option | Found by pagination keywords | At the call site |
| Prefetch and `ensureQueryData` functions | Yes, per operation | Prefetch with `usePrefetch` | No | No | No |
| Query key functions | Yes | Yes | Yes | Yes | No, the key is `[method, path, params]` |
| Frameworks | React | React, Vue, Svelte, Solid, Angular | React, Vue | React, Vue, Svelte, Solid, Angular, Preact | React |
diff --git a/docs/src/content/docs/guides/faq.md b/docs/src/content/docs/guides/faq.md
index a228aef..ec82f8f 100644
--- a/docs/src/content/docs/guides/faq.md
+++ b/docs/src/content/docs/guides/faq.md
@@ -88,7 +88,7 @@ The generated hooks reject on an error response, so `error` and `isError` are se
### How do infinite queries get generated?
-An operation gets `useXxxInfinite` when it has a query parameter with the name given by `--pageParam` (default `page`) and its response has the property given by `--nextPageParam` (default `nextPage`, dot notation for nested values). See [Usage](/guides/usage/#using-the-generated-useinfinitequery-hooks).
+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?
diff --git a/docs/src/content/docs/guides/usage.mdx b/docs/src/content/docs/guides/usage.mdx
index 0a7ff9d..bcd83f5 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 31deaf5..d8e356e 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 445c892..426f000 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";
From 7f0f6dfb77b84749a5b17dcb14a15019ca3a959e Mon Sep 17 00:00:00 2001
From: Urata Daiki <7nohe@users.noreply.github.com>
Date: Sun, 15 Nov 2026 11:31:12 +0900
Subject: [PATCH 3/5] docs: say that a custom query key replaces the options in
the key
The key is [operationKey, ...(queryKey ?? [clientOptions])], so a key passed to the hook is not combined with the options, as the two example pages said.
---
docs/src/content/docs/examples/nextjs.md | 2 +-
docs/src/content/docs/examples/react-router.md | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/src/content/docs/examples/nextjs.md b/docs/src/content/docs/examples/nextjs.md
index d095404..4554739 100644
--- a/docs/src/content/docs/examples/nextjs.md
+++ b/docs/src/content/docs/examples/nextjs.md
@@ -120,7 +120,7 @@ export default function Pets() {
}
```
-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 built from both, so anything different is a different cache entry and the browser fetches again.
+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
diff --git a/docs/src/content/docs/examples/react-router.md b/docs/src/content/docs/examples/react-router.md
index e9c783b..1e80b3b 100644
--- a/docs/src/content/docs/examples/react-router.md
+++ b/docs/src/content/docs/examples/react-router.md
@@ -98,7 +98,7 @@ export default function Index({ loaderData }: Route.ComponentProps) {
}
```
-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 built from both, so anything different is a different cache entry and the browser fetches again.
+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
From a2a0a78d48aa8c346cb74a8b85c5c7e9b743dc4e Mon Sep 17 00:00:00 2001
From: Urata Daiki <7nohe@users.noreply.github.com>
Date: Sun, 15 Nov 2026 11:35:44 +0900
Subject: [PATCH 4/5] docs: drop the claim that @hey-api/openapi-ts is
FSL-licensed
The package and its repository are MIT. The migration guide keeps the fact that matters: it is no longer a dependency.
---
docs/src/content/docs/guides/migrating-to-v4.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/src/content/docs/guides/migrating-to-v4.mdx b/docs/src/content/docs/guides/migrating-to-v4.mdx
index fb86865..fbe9c4c 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.
From 26770c1078f0050bb3a372a691ee7054065dd8e6 Mon Sep 17 00:00:00 2001
From: Urata Daiki <7nohe@users.noreply.github.com>
Date: Sun, 15 Nov 2026 11:52:25 +0900
Subject: [PATCH 5/5] docs: lead the comparison with what sets this library
apart
The page was accurate but opened by conceding that the other tools are
broader, listed the features they have more of, and ended on when not
to use this library. The facts are the same; the order is not:
- "What sets it apart" comes first, with the numbers read from the
benchmark results: fastest on every specification measured, fewest
packages, no type errors in the output, everything generated without
options, ensureQueryData functions, CI and agent support, SemVer.
- The measured table moves above the feature table, and the feature
table lists the rows that differ first (suspense, prefetch and
ensureQueryData split into their own rows, plus the release line).
- Each "Compared with" section opens with why to choose this library and
then says when to choose the other tool.
- "When another tool fits better" stays, followed by a short summary.
---
docs/src/content/docs/guides/comparison.mdx | 106 ++++++++++++--------
1 file changed, 66 insertions(+), 40 deletions(-)
diff --git a/docs/src/content/docs/guides/comparison.mdx b/docs/src/content/docs/guides/comparison.mdx
index 97d2eb0..c39c752 100644
--- a/docs/src/content/docs/guides/comparison.mdx
+++ b/docs/src/content/docs/guides/comparison.mdx
@@ -1,6 +1,6 @@
---
title: Comparison
-description: How OpenAPI React Query Codegen differs from Orval, Kubb, Hey API and openapi-react-query in what they generate for TanStack Query, the frameworks and HTTP clients they support, and when to choose which.
+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 {
@@ -11,30 +11,23 @@ import {
typeErrors,
} from "../../../data/benchmarks";
-Several tools turn an OpenAPI document into code for TanStack Query. They differ mostly in scope. This library does one thing: React and TanStack Query v5, from one command with no configuration file. The others are broader, and that is often the reason to choose them.
+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");
-This page 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 here is out of date, please [open an issue](https://github.com/7nohe/openapi-react-query-codegen/issues).
+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.
-## At a glance
+## What sets it apart
-| | 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")` |
-| `queryOptions` factories | Yes | Yes (`getXxxQueryOptions`) | Yes, the default output | Yes, the default output | `$api.queryOptions(...)` |
-| Suspense hooks | Yes | With `useSuspenseQuery` | With `suspense` | No | `$api.useSuspenseQuery` |
-| Infinite queries | Found by the `--pageParam` query parameter | `useInfinite` and `useInfiniteQueryParam` | `infinite` option | Found by pagination keywords | At the call site |
-| Prefetch and `ensureQueryData` functions | Yes, per operation | Prefetch with `usePrefetch` | No | No | No |
-| Query key functions | Yes | Yes | Yes | Yes | No, the key is `[method, path, params]` |
-| 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 |
-| 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 |
-| 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 |
-| Configuration | Command line flags | `orval.config.ts` | `kubb.config.ts` | `openapi-ts.config.ts` | Command line flags |
-| Check for stale output in CI | `--check` | `--outdated` | `--dry-run` shows planned changes | No | `--check` |
-| Errors as JSON | `--json` | No | `--reporter json` | No | 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.
+- **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
@@ -42,7 +35,7 @@ Where a tool has no helper of its own, such as prefetching with Kubb or Hey API,
Tool
-
Generation time, GitHub REST API ({operations("github").toLocaleString("en-US")} operations)
+
Generation time, GitHub REST API ({githubOperations} operations)
Packages added
Type errors in the output, Stripe / GitHub
@@ -50,8 +43,8 @@ Where a tool has no helper of its own, such as prefetching with Kubb or Hey API,
{tools.map((tool, index) => (
-
{tool.name}
-
{generationSeconds("github")[index].value.toFixed(2)} s
+
{tool.own ? {tool.name} : tool.name}
+
{seconds[index].value.toFixed(2)} s
{addedPackages[index].value}
{typeErrors("stripe")[index].value} / {typeErrors("github")[index].value}
@@ -61,38 +54,71 @@ Where a tool has no helper of its own, such as prefetching with Kubb or Hey API,
-How these were measured, the versions and the other specifications are on the [Benchmarks](/guides/benchmarks/) page.
+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.
-## Orval
+## Feature by feature
-[Orval](https://orval.dev) generates hooks per operation too, with `queryOptions` factories, key functions and optional suspense, infinite, prefetch and invalidation helpers. It covers far more than React: Vue, Svelte, Solid and Angular with TanStack Query, SWR, Pinia Colada, and Zod, Valibot or Effect schemas. Its mocks use MSW with Faker, so they return random data.
+| | 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 |
-Choose Orval when you need one of those targets, random mock data, or a configuration file with per-operation overrides. Choose this library when you want React and TanStack Query without configuration: suspense hooks, prefetch and `ensureQueryData` functions are generated for every operation with no option to turn on, the generator installs {addedPackages[0].value} packages, and it is faster on large specifications.
+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.
-## Kubb
+## Compared with Kubb
-[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`. Other plugins add Vue Query, SWR, Zod, MSW and Faker, and you can write your own. It is configured in `kubb.config.ts`.
+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 or generate something no fixed generator offers. Choose this library when the fixed output is what you want and you would rather not maintain a configuration.
+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.
-## Hey API
+## Compared with Hey API
-[Hey API](https://heyapi.dev) (`@hey-api/openapi-ts`) is also plugin-based. Its TanStack Query plugin generates options factories and query keys that you pass to `useQuery`, `useInfiniteQuery` and `useMutation` yourself, for React, Vue, Svelte, Solid, Angular and Preact. It has the widest choice of HTTP clients here, and Zod and Valibot plugins. The project asks you to pin an exact version while it is before 1.0.
+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, see [Migrating to v4](/guides/migrating-to-v4/).
+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, another HTTP client, or runtime validation. Choose this library when you want ready-made hooks, suspense variants and server-side helpers per operation, and output that only changes in a breaking way between major versions.
+Choose Hey API when you need a framework other than React, an HTTP client other than fetch and axios, or Zod or Valibot validation.
-## openapi-typescript and openapi-react-query
+## Compared with openapi-typescript and openapi-react-query
-[openapi-typescript](https://openapi-ts.dev) generates types only. `openapi-fetch` and `openapi-react-query` are small runtime packages that use those types: you call `$api.useQuery("get", "/pets/{petId}", ...)` with the method and the path as strings, so there is nothing to regenerate except the types and very little code in your repository.
+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 project 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. If you are moving on from it, see [Migrating from openapi-react-query](/guides/migrating-from-openapi-react-query/).
+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`.
-## When this library is not the right choice
+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.