OpenAPI React Query Codegen

Code generator for TanStack Query (React Query) based on your OpenAPI schema — queryOptions factories following the official TanStack Query v5 pattern, plus ready-to-use hooks, prefetch, ensure, suspense, and infinite query helpers.

📖 Documentation · Migrating to v3

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 clients generated by @hey-api/openapi-ts (fetch and axios)

Quick start

npm install -D @7nohe/openapi-react-query-codegen
npx openapi-rq -i ./petstore.yaml

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, SSR recipes, and infinite query usage.

How it compares

	This library	@hey-api tanstack-query plugin	Orval
queryOptions / infiniteQueryOptions factories (TanStack v5 pattern)	✅	✅	❌
Ready-to-use hooks (useQuery / suspense / infinite variants)	✅	❌ (options only)	✅
SSR helpers (prefetchQuery / prefetchInfiniteQuery / ensureQueryData)	✅	❌	Partial (usePrefetch)
Hierarchical query keys for granular invalidation	✅	✅ (tags)	Partial
Stable release line	✅ SemVer	pre-1.0, frequent breaking changes	✅
MSW mock generation	❌ (out of scope)	❌	✅
Vue / Solid / Svelte / Angular	❌ React-focused	✅	✅

Scope: this library is deliberately React-focused and does not generate API mocks — use Orval if MSW mocks are your priority, or hey-api's own plugin if you need non-React frameworks.

Stability policy

This library builds on @hey-api/openapi-ts, which is pre-1.0 and moves fast. We pin the exact hey-api version and absorb its breaking changes for you: hey-api upgrades land here only after our full snapshot-test suite passes, and are released as minor versions. Your generated API surface follows SemVer — breaking output changes only happen in major versions, with a migration guide.

Requirements

• Node.js 22.18+
• @tanstack/react-query 5.x (peer dependency)
• typescript 5.x or 6.x, ts-morph 28.x, commander 12–15 (peer dependencies)

License

MIT