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