Generate TanStack Query (React Query) code from your OpenAPI spec:
queryOptionsfactories following the official TanStack Query v5 pattern, ready-to-use hooks, prefetch, ensure, suspense and infinite query helpers, and the typed fetch or axios client they call.
📖 Documentation · Getting started · Migrating to v4 · Coming from openapi-react-query · Benchmarks
queryOptions/infiniteQueryOptionsfactories for every GET operation — the TanStack Query v5 recommended pattern, composable withuseQuery,useQueries,useSuspenseQuery,prefetchQuery,ensureQueryData, andsetQueryDatawith full type safety- Custom hooks:
useQuery,useSuspenseQuery,useMutation,useInfiniteQuery, anduseSuspenseInfiniteQueryvariants per operation - SSR helpers:
prefetchQuery,prefetchInfiniteQuery, andensureQueryDatafunctions per operation — ready for Next.js App Router hydration - Hierarchical query keys with exported key constants and functions: invalidate one exact query, all infinite pages of an operation, or every cache entry of an operation with a single prefix
- Pure TypeScript client (types, SDK functions and a small fetch or axios runtime) generated from the same OpenAPI 3.0/3.1 document — no separate client generator to install
- MSW mocks from the same spec (
--mock msw): typed mock data and a request handler per operation, with fixed values taken from the spec's examples — build the frontend before the backend exists, and reuse the handlers in tests - CI- and agent-friendly:
--checkfails CI when committed output is out of date,--jsonprints errors as machine-readable JSON,--agentsMdkeeps a guide in yourAGENTS.mdthat lets a coding agent look one operation up instead of reading the generated files, and the package ships anAGENTS.mdfor coding agents
Note
v4 is in beta, and this README describes it. Install it with @beta; a plain npm install still gets v3, whose README and docs are in the v3 branch. What changes from v3 is in Migrating to v4.
Try it without installing:
npx @7nohe/orqc@beta -i ./petstore.yamlThen add it to your project, next to TanStack Query:
npm install -D @7nohe/openapi-react-query-codegen@beta
npm install @tanstack/react-queryKeep the command in a package.json script. A script only runs the version installed in the project, so the output always matches your lockfile:
{ "scripts": { "codegen": "orqc -i ./petstore.yaml" } }npm run codegenThis writes the client to openapi/requests/ and the TanStack Query code to openapi/queries/ (change the folder with -o):
import { useQuery } from "@tanstack/react-query";
import { findPetsOptions } from "./openapi/queries";
function Pets() {
const { data } = useQuery(findPetsOptions({ query: { limit: 10 } }));
// ...or use the generated hook directly: useFindPets({ query: { limit: 10 } })
}See the documentation for CLI options, usage (SSR, infinite queries, mutations), mocking with MSW and CI and coding agents.
| Example | Folder |
|---|---|
| Vite + React | examples/react-app |
| Next.js (App Router) | examples/nextjs-app |
| TanStack Router | examples/tanstack-router-app |
| React Router | examples/react-router-app |
Important
This project publishes only the scoped @7nohe/openapi-react-query-codegen and its short name @7nohe/orqc. The unscoped openapi-react-query-codegen and openapi-rq and the copies under other scopes on npm are published by third parties, not by this project.
Built only for React and TanStack Query v5: one command, with no configuration file, gives every GET operation a query hook, a suspense hook, a queryOptions factory, a prefetch function and an ensureQueryData function, and every other operation a mutation hook. The Comparison page has the details and when another tool fits better.
| This library | Orval | Kubb | Hey API | openapi-react-query | |
|---|---|---|---|---|---|
Hooks per operation (useQuery, useMutation) |
✅ always | ✅ | With hooks: true |
❌ (documented output is options factories) | Runtime wrapper ($api.useQuery("get", "/pets")) |
| Suspense hooks | ✅ always | With useSuspenseQuery |
With suspense |
❌ | ✅ ($api.useSuspenseQuery) |
| Prefetch functions | ✅ always | With usePrefetch |
❌ | ❌ | ❌ |
ensureQueryData functions |
✅ always | ❌ | ❌ | ❌ | ❌ |
queryOptions factories (TanStack v5 pattern) |
✅ | ✅ (getXxxQueryOptions) |
✅ | ✅ | ✅ ($api.queryOptions) |
| Query key functions | ✅ | ✅ | ✅ | ✅ | ❌ |
| Check for stale output in CI | ✅ --check |
✅ --outdated |
--dry-run shows planned changes |
❌ | ✅ --check |
| Configuration | CLI flags | orval.config.ts |
kubb.config.ts |
openapi-ts.config.ts |
CLI flags |
| Release line | ✅ SemVer | ✅ v8 | ✅ v5 | Before 1.0 | |
| MSW mocks | ✅ fixed values (--mock msw) |
✅ random values (Faker) | ✅ random values (Faker) | In progress | ❌ |
| Vue / Svelte / Solid / Angular | ❌ React only | ✅ | Vue | ✅ | ❌ |
| Generation time, GitHub REST API (1,272 operations)¹ | 0.46 s | 4.31 s | 2.98 s | 2.98 s | 2.10 s |
| Packages added by installing the generator¹ | 9 (2.1 MB) | 89 (101.5 MB) | 91 (37.4 MB) | 51 (10.8 MB) | 35 (20.5 MB) |
| Type errors in the generated code, Stripe / GitHub APIs¹ | 0 / 0 | 219 / 1 | 0 / 0 | 274 / 0 | 0 / 0 |
The feature rows were checked against each tool's documentation on 2026-11-15 (Orval 8.48.0, Kubb 5.20.1 with @kubb/plugin-react-query 5.10.3, @hey-api/openapi-ts 0.99.0, openapi-react-query 0.5.4).
¹ 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, Orval 8.46.0, Kubb 5.15.4 with @kubb/plugin-react-query 5.9.0, @hey-api/openapi-ts 0.99.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 page; the scripts are in benchmarks/.
Scope: this library is deliberately React-focused — use Orval, Kubb or Hey API if you need another framework. Its MSW mocks answer with fixed values taken from the spec and keep no state; use Orval or Kubb if you want randomly generated mock data.
Coming from openapi-typescript / openapi-fetch / openapi-react-query? See the migration guide.
The client generator is part of this package, so the generated requests/ directory and the hooks built on it change together and follow SemVer: breaking output changes only happen in major versions, with a migration guide (see Migrating to v4 if you are coming from v3, where the client was produced by @hey-api/openapi-ts).
- Node.js 24+
@tanstack/react-query5.x (peer dependency)commander12–15 (peer dependency)- TypeScript 5.x, 6.x or 7.x to compile the generated code. It is not a peer dependency: the generator does not use the
typescriptpackage.
Issues and pull requests are welcome. See the contributing guide for the development setup.