Package Exports
- @openapi-qraft/react
- @openapi-qraft/react/Unstable_QraftSecureRequestFn
- @openapi-qraft/react/callbacks
- @openapi-qraft/react/callbacks/cancelQueries
- @openapi-qraft/react/callbacks/ensureInfiniteQueryData
- @openapi-qraft/react/callbacks/ensureQueryData
- @openapi-qraft/react/callbacks/fetchInfiniteQuery
- @openapi-qraft/react/callbacks/fetchQuery
- @openapi-qraft/react/callbacks/getInfiniteQueryData
- @openapi-qraft/react/callbacks/getInfiniteQueryKey
- @openapi-qraft/react/callbacks/getInfiniteQueryState
- @openapi-qraft/react/callbacks/getMutationCache
- @openapi-qraft/react/callbacks/getMutationKey
- @openapi-qraft/react/callbacks/getQueriesData
- @openapi-qraft/react/callbacks/getQueryData
- @openapi-qraft/react/callbacks/getQueryKey
- @openapi-qraft/react/callbacks/getQueryState
- @openapi-qraft/react/callbacks/index
- @openapi-qraft/react/callbacks/invalidateQueries
- @openapi-qraft/react/callbacks/isFetching
- @openapi-qraft/react/callbacks/isMutating
- @openapi-qraft/react/callbacks/operationInvokeFn
- @openapi-qraft/react/callbacks/prefetchInfiniteQuery
- @openapi-qraft/react/callbacks/prefetchQuery
- @openapi-qraft/react/callbacks/refetchQueries
- @openapi-qraft/react/callbacks/removeQueries
- @openapi-qraft/react/callbacks/resetQueries
- @openapi-qraft/react/callbacks/setInfiniteQueryData
- @openapi-qraft/react/callbacks/setQueriesData
- @openapi-qraft/react/callbacks/setQueryData
- @openapi-qraft/react/callbacks/useInfiniteQuery
- @openapi-qraft/react/callbacks/useIsFetching
- @openapi-qraft/react/callbacks/useIsMutating
- @openapi-qraft/react/callbacks/useMutation
- @openapi-qraft/react/callbacks/useMutationState
- @openapi-qraft/react/callbacks/useQueries
- @openapi-qraft/react/callbacks/useQuery
- @openapi-qraft/react/callbacks/useSuspenseInfiniteQuery
- @openapi-qraft/react/callbacks/useSuspenseQueries
- @openapi-qraft/react/callbacks/useSuspenseQuery
- @openapi-qraft/react/package.json
- @openapi-qraft/react/qraftPredefinedParametersRequestFn
- @openapi-qraft/react/unstable__responseUtils
Readme
@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.
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.
Installation
First, install the core package for your project:
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:
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:
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.
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.
Example with useQuery()
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 <div>Loading...</div>;
}
if (error) {
return <div>Error: {error.message}</div>;
}
return <div>Pet Name: {pet?.name}</div>;
}
export default function App() {
return (
<QueryClientProvider client={queryClient}>
<ExamplePetDetails petId={123456} />
</QueryClientProvider>
);
}
Example with useMutation()
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 (
<form
onSubmit={(event) => {
event.preventDefault();
const formData = new FormData(event.currentTarget);
/**
* Executes the request`:
* ###
* POST /entities/3e3e-3e3e-3e3e/documents
* x-monite-version: 2023-09-01
*
* {"company_tax_id_verification": ["verification-id"]}
**/
mutation.mutate({
company_tax_id_verification: [
String(formData.get('company_tax_id_verification')),
],
});
}}
>
<input name="company_tax_id_verification" />
<button>Submit</button>
</form>
);
}
export default function App() {
return (
<QueryClientProvider client={queryClient}>
<EntityForm entityId="3e3e-3e3e-3e3e" />
</QueryClientProvider>
);
}
Example with useInfiniteQuery()
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 (
<div>
{infiniteQuery.data?.pages.map((page, pageIndex) => (
<ul key={pageIndex}>
{page.map((post) => (
<li key={post.id}>{post.title}</li>
))}
</ul>
))}
<button
onClick={() => {
// ⬇︎ Executes GET /posts?limit=10&page=2
infiniteQuery.fetchNextPage();
}}
>
Load More
</button>
</div>
);
}
export default function App() {
return (
<QueryClientProvider client={queryClient}>
<PostList />
</QueryClientProvider>
);
}
Supported Hooks
-
useQuery(...)
-
useMutation(...)
-
useInfiniteQuery(...)
-
useQueries(...)
-
useSuspenseQuery(...)
-
useSuspenseInfiniteQuery(...)
-
useSuspenseQueries(...)
-
useIsFetching(...)
-
useMutationState(...)
-
useIsMutating(...)
QueryClient
methods
-
fetchQuery(...)
-
fetchInfiniteQuery(...)
-
prefetchQuery(...)
-
prefetchInfiniteQuery(...)
-
getQueryData(...)
-
getQueriesData(...)
-
setQueryData(...)
-
getQueryState(...)
-
setQueriesData(...)
-
invalidateQueries(...)
-
refetchQueries(...)
-
cancelQueries(...)
-
removeQueries(...)
-
resetQueries(...)
-
isFetching(...)
-
isMutating(...)
Qraft Utility Functions
-
getQueryKey(...)
-
setInfiniteQueryData(...)
-
getInfiniteQueryKey(...)
-
getInfiniteQueryData(...)
-
getInfiniteQueryState(...)
-
getMutationKey(...)
Contributing
Contributions are welcome! If you have suggestions or want to improve @openapi-qraft/react
, please feel free to submit
a pull request or open an issue.
License
@openapi-qraft/react
is licensed under the MIT License. See the LICENSE file for more details.