# @openapi-qraft/react
`@openapi-qraft/react` is a modular TypeScript client designed to facilitate type-safe API requests in React
applications,
leveraging the power of **TanStack Query v5**. It utilizes a Proxy-based architecture to dynamically generate
hooks with typed parameters, ensuring that your API requests are both type-safe and efficient.
Read the full documentation at [openapi-qraft.github.io/openapi-qraft](https://openapi-qraft.github.io/openapi-qraft/).
## 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](https://tanstack.com/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.
## Installation
First, install the core package for your project:
```bash
npm install @openapi-qraft/react
```
If your project doesn't already include `@tanstack/react-query`, you'll also need to install it. This package is
essential for handling server state in React applications:
```bash
npm install @tanstack/react-query
```
## Getting Started
To get started with OpenAPI Qraft, you need to generate types and service definitions from your OpenAPI Document.
These are used to create type-safe hooks and interact with your API.
### 1. Generate OpenAPI Types & Services
Run the following command in the root directory of your project using your package manager:
```bash
npx @openapi-qraft/cli --plugin tanstack-query-react --plugin openapi-typescript \
--output-dir src/api https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml
```
> 💡 For stable project maintenance, it's recommended to install the CLI generator as a dev dependency.
> Read more about installation in the [documentation](https://openapi-qraft.github.io/openapi-qraft/docs/getting-started/installation).
### 2. Use the generated services in your React application
Below are examples demonstrating how to use the generated services in your React application with
`useQuery`, `useMutation`, and `useInfiniteQuery` hooks from [TanStack Query](https://tanstack.com/query/latest).
#### Example with `useQuery()`
```tsx title="src/App.tsx"
import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createAPIClient } from './api'; // generated by OpenAPI Qraft
const queryClient = new QueryClient();
// Use `createAPIClient(...)` to initialize the API client as needed.
// It's a lightweight 🪶 shortcut for working with TanStack Query 🌴
const api = createAPIClient({
requestFn,
queryClient,
baseUrl: 'https://petstore3.swagger.io/api/v3',
});
function ExamplePetDetails({ petId }: { petId: number }) {
/**
* Executes the request to the API on mount:
* ###
* GET /pet/123456
**/
const {
data: pet,
isPending,
error,
} = api.pet.getPetById.useQuery({
path: { petId },
});
if (isPending) {
return
Loading...
;
}
if (error) {
return
Error: {error.message}
;
}
return
Pet Name: {pet?.name}
;
}
export default function App() {
return (
);
}
```
#### Example with `useMutation()`
```tsx title="src/App.tsx"
import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createAPIClient } from './api'; // generated by OpenAPI Qraft
const queryClient = new QueryClient();
const api = createAPIClient({
requestFn,
queryClient,
baseUrl: 'https://petstore3.swagger.io/api/v3',
});
function EntityForm({ entityId }: { entityId: string }) {
const mutation = api.entities.postEntitiesIdDocuments.useMutation({
// ☝️ useMutation() can be used with `undefined` parameters
path: {
entity_id: entityId,
},
header: {
'x-monite-version': '2023-09-01',
},
});
return (
);
}
export default function App() {
return (
);
}
```
#### Example with `useInfiniteQuery()`
```tsx title="src/PostList.tsx"
import { requestFn } from '@openapi-qraft/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createAPIClient } from './api'; // generated by OpenAPI Qraft
const queryClient = new QueryClient();
const api = createAPIClient({
requestFn,
queryClient,
baseUrl: 'https://petstore3.swagger.io/api/v3',
});
/**
* Executes the initial request:
* ###
* GET /posts?limit=10&page=1
**/
function PostList() {
const infiniteQuery = api.posts.getPosts.useInfiniteQuery(
{ query: { limit: 10 } },
{
getNextPageParam: (lastPage, allPages, lastPageParams) => {
if (lastPage.length < 10) return; // if less than 10 items, there are no more pages
return {
query: {
page: Number(lastPageParams.query?.page) + 1,
},
};
},
initialPageParam: {
query: {
page: 1, // will be used in initial request
},
},
}
);
return (