Skip to content

About

Generate TanStack Query (React Query) hooks, queryOptions factories and a typed fetch/axios client from your OpenAPI spec. CLI: orqc

Topics

Resources

Stars

430 stars

Watchers

3 watching

Forks

Repository files navigation

OpenAPI React Query Codegen (orqc)

Generate TanStack Query (React Query) code from your OpenAPI spec: queryOptions factories 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.

npm npm beta npm downloads license

📖 Documentation · Getting started · Migrating to v4 · Coming from openapi-react-query · Benchmarks

The findPets operation of an OpenAPI document. Running npx @7nohe/orqc@beta -i openapi.yaml generates useFindPets, findPetsOptions, useFindPetsSuspense, prefetchUseFindPets and UseFindPetsKeyFn in openapi/queries, plus a typed client in openapi/requests. An app then calls useFindPets.

Features

  • queryOptions / infiniteQueryOptions factories for every GET operation — the TanStack Query v5 recommended pattern, composable with useQuery, useQueries, useSuspenseQuery, prefetchQuery, ensureQueryData, and setQueryData with full type safety
  • Custom hooks: useQuery, useSuspenseQuery, useMutation, useInfiniteQuery, and useSuspenseInfiniteQuery variants per operation
  • SSR helpers: prefetchQuery, prefetchInfiniteQuery, and ensureQueryData functions 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: --check fails CI when committed output is out of date, --json prints errors as machine-readable JSON, --agentsMd keeps a guide in your AGENTS.md that lets a coding agent look one operation up instead of reading the generated files, and the package ships an AGENTS.md for coding agents

Quick start

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.yaml

Then add it to your project, next to TanStack Query:

npm install -D @7nohe/openapi-react-query-codegen@beta
npm install @tanstack/react-query

Keep 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 codegen

This 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.

Examples

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.

How it compares

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 ⚠️ maintenance mode
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.

Stability policy

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).

Requirements

  • Node.js 24+
  • @tanstack/react-query 5.x (peer dependency)
  • commander 12–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 typescript package.

Contributing

Issues and pull requests are welcome. See the contributing guide for the development setup.

License

MIT

About

Generate TanStack Query (React Query) hooks, queryOptions factories and a typed fetch/axios client from your OpenAPI spec. CLI: orqc

Topics

Resources

Stars

430 stars

Watchers

3 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages