Skip to main content
Version: 1.x

Overview

Meet OpenAPI Qraft: your go-to library for crafting type-safe API Hooks for React apps from OpenAPI Documents. By leveraging TanStack Query v5, it introduces a smart Proxy-based API client design to seamlessly generate custom hooks with strictly-typed parameters.

Features​

  • Type-safe API Requests: Utilize TypeScript for type-safe API requests, reducing runtime errors and improving developer experience.
  • Modular Design: Customize the utility with a set of callbacks to handle API calls according to your project's needs.
  • Integration with TanStack Query v5: Seamlessly integrate with TanStack Query for handling server state, caching, and data synchronization.
  • Dynamic Proxy-Based Hooks: Automatically generate React Query hooks for your API endpoints without manual boilerplate.
  • SSR Support: OpenAPI Qraft fully supports Server-Side Rendering (SSR) at the same level as TanStack Query, including support for Next.js /app directory.

Fast Run​

import { createAPIClient } from './api'; // generated by OpenAPI Qraft

import { QraftContext, requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

/**
 * The `createAPIClient(...)` function is generated by OpenAPI Qraft
 * The `qraft` object could be created in a separate file and imported,
 * or created multiple times in different components.
 * It's just a typed shortcut to TanStack Query Hooks!
 */
const qraft = createAPIClient();

function ExamplePetDetails({ petId }: { petId: number }) {
  const {
    data: pet,
    isPending,
    error,
  } = qraft.pet.getPetById.useQuery({ // ⬅︎ Qraft's magic ✨
    path: { petId },
  });

  if (isPending) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return <div>Pet Name: {pet?.name}</div>;
}

const queryClient = new QueryClient();

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <QraftContext.Provider
        value={{
          baseUrl: 'https://petstore3.swagger.io/api/v3', // the base URL of the API
          requestFn, // the request function to use, could be fully customized
        }}
      >
        <ExamplePetDetails petId={123456} />
      </QraftContext.Provider>
    </QueryClientProvider>
  );
}

Supported TanStack Query Features​

Hooks​

QueryClient methods​

Qraft Utility Functions​