@ternaus/openapi-react-query

Fork of openapi-react-query in openapi-ts/openapi-typescript, maintained by Vladimir Iglovikov. The original authorship, Git history, and MIT license are preserved.

@ternaus/openapi-react-query is a typed client for @tanstack/react-query that uses your OpenAPI schema.

TypeScript checks request fields and infers response shapes from the types generated by openapi-typescript. The client sends requests through openapi-fetch.

Setup

Requires React 19 and TanStack Query 5.

Install this library along with openapi-fetch and openapi-typescript:

npm i @ternaus/openapi-react-query @ternaus/openapi-fetch
npm i -D @ternaus/openapi-typescript typescript

Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:

npx @ternaus/openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts

Usage

Once your types have been generated from your schema, you can create a fetch client, a react-query client and start querying your API.

import createFetchClient from "@ternaus/openapi-fetch";
import createClient from "@ternaus/openapi-react-query";
import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({
  baseUrl: "https://myapi.dev/v1/",
});
const $api = createClient(fetchClient);

const MyComponent = () => {
  const { data, error, isPending } = $api.useQuery(
    "get",
    "/blogposts/{post_id}",
    {
      params: {
        path: { post_id: 5 },
      },
    }
  );

  if (isPending || !data) return "Loading...";

  if (error) return `An error occurred: ${error.message}`;

  return <div>{data.title}</div>;
};

You can find more information about createFetchClient in the openapi-fetch documentation.

Clients share a cache by normalized baseUrl. Use createClient(fetchClient, { cacheKey: "user-123" }) to separate users or middleware on the same server. Normal and infinite queries use different keys. Reuse queryOptions(...).queryKey for cache access and invalidation.

HTTP errors reject with their parsed payload. An empty error body produces an Error with the status in its message and the original Response in cause. Empty successful queries return null.

📓 Docs

View Docs