OpenAPI React Query Codegen

The generator provides several key automation features for React applications:

• Custom React Hooks: Automatically generates hooks utilizing React Query's core primitives: useQuery, useSuspenseQuery, useMutation, and useInfiniteQuery.
• Data Fetching Utilities: Generates custom functions that wrap React Query's ensureQueryData and prefetchQuery for efficient data prefetching and synchronization.
• Query Key Management: Generates structured query keys and query functions to facilitate robust query caching.
• TypeScript Client Integration: Produces pure TypeScript clients by leveraging @hey-api/openapi-ts.

The tool provides three main capabilities for building type-safe React applications:

1. React Query Hooks: Generates custom hooks that wrap TanStack Query's core primitives: useQuery, useSuspenseQuery, useMutation, and useInfiniteQuery.
2. Prefetching & Router Integration: Generates custom functions utilizing React Query's ensureQueryData and prefetchQuery. This allows for seamless integration with modern frameworks like Next.js and Remix for server-side prefetching or router-based data loading.
3. Pure TypeScript Clients: Leverages @hey-api/openapi-ts to generate pure TypeScript clients, enabling type-safe API calls even in environments where you are not using React Query.

To preview the documentation site in your local development environment, run the following command from the root of the repository. This uses pnpm with a filter to target the docs package.

pnpm --filter docs dev

To contribute to this project, ensure you have the following prerequisites installed:

• Node.js v24 or later
• pnpm v9

Then, install the project dependencies using pnpm:

pnpm install

Use the following commands to run tests, linting, and other maintenance tasks:

• Run tests: pnpm test
• Run linter: pnpm lint
• Run linter and fix: pnpm lint:fix
• Update snapshots: pnpm snapshot
• Build example and validate generated code: This command builds the project, generates the API in the @7nohe/react-app package, and then runs tests on the generated code to ensure correctness.
• Preview the docs: Starts the documentation server for the docs package.

# Build example and validate generated code
npm run build && pnpm --filter @7nohe/react-app generate:api && pnpm --filter @7nohe/react-app test:generated 

# Preview the docs
pnpm --filter docs dev

You can use the auto-generated React Query hooks directly to fetch data. These hooks are typically exported from ../openapi/queries.

If you need more control, you can use the pure TypeScript SDK functions (defined in openapi/requests/sdk.gen.ts or the openapi/requests/services.gen.ts shim) with the standard @tanstack/react-query useQuery hook. To maintain consistency and type safety, use the auto-generated query key function (e.g., useFindPetsKey) provided by the generated files.

import { useFindPets } from "../openapi/queries";
function App() {
  const { data } = useFindPets();

  return (
    <div className="App">
      <h1>Pet List</h1>
      <ul>{data?.map((pet) => <li key={pet.id}>{pet.name}</li>)}</ul>
    </div>
  );
}

The codegen automatically generates infinite query hooks in infiniteQueries.ts if your OpenAPI schema meets two criteria:

1. A parameter name matches the pageParam option (e.g., page).
2. A response property name matches the nextPageParam option (e.g., nextPage).

Configuration Details:

• initialPageParam: Sets the starting page (defaults to 1).
• nextPageParam: Supports dot notation for accessing nested values in the response (e.g., meta.next).

import { useFindPaginatedPetsInfinite } from "@/openapi/queries/infiniteQueries";

const { data, fetchNextPage } = useFindPaginatedPetsInfinite({
  query: { tags: [], limit: 10 }
});

The codegen provides suspense-compatible hooks (e.g., useFindPetsSuspense) exported from ../openapi/queries/suspense. These hooks are designed to work with React's <Suspense> boundary, allowing you to handle loading states at a component tree level rather than inside the hook itself.

import { useFindPetsSuspense } from "../openapi/queries/suspense";

function ChildComponent() {
  const { data } = useFindPetsSuspense({
    query: { tags: [], limit: 10 },
  });

  return <ul>{data?.map((pet, index) => <li key={pet.id}>{pet.name}</li>)}</ul>;
}

function ParentComponent() {
  return (
    <>
      <Suspense fallback={<>loading...</>}>
        <ChildComponent />
      </Suspense>
    </>
  );
}