@rocketmakers/api-swr
is a TypeScript library that provides a convenient React wrapper around SWR state management library. It allows developers to easily interface with a TypeScript API client while managing client side state.
Install from npm using your package manage of choice:
npm install @rocketmakers/api-swr
pnpm add @rocketmakers/api-swr
yarn add @rocketmakers/api-swr
- Controller factory - one created for each API, used to create a "controller" for each tag within the API client.
- Controller - one created for each tag within the API client, used to create the endpoint hooks.
- Endpoint hook - a hook consumed by React components, used to retrieve data, run side effects, and manage cache.
- Recommended file structure
- The Provider
- Custom API client (only relevant if not using a generated OpenAP client, otherwise see quick start below)
- useQuery (for GET requests)
- useMutation (for POST/PUT/PATCH/DELETE requests)
- useInfiniteQuery (for paged GET requests with infinite loading)
This quick start guide assumes you're working from a generated TypeScript OpenAPI client, don't worry if you're not though, it's dead easy to work from a hand written client, see here.
To allow all endpoint hooks to read the global cache, your app should be wrapped with the API SWR provider.
NOTE: If you are an Armstrong user, it's useful to make sure the Armstrong provider is outside the API SWR provider. This will allow you to dispatch Armstrong toast from your API SWR processing hook.
import * as React from 'react';
import { ApiSwrProvider } from '@rocketmakers/api-swr';
export const App: React.FC<React.PropsWithChildren> = ({ children }) => {
return <ApiSwrProvider>{children}</ApiSwrProvider>;
};
API SWR requires a controller factory for each API that you want to integrate. This factory is used for creating controllers. You should pass a base URL for the deployed API.
import { openApiControllerFactory } from '@rocketmakers/api-swr';
export const apiFactory = openApiControllerFactory({
basePath: 'https://my.example.api/dev',
});
One controller should be created for each tag within the OpenAPI client. Tags are often used for splitting generated clients by backend controller, (e.g. "auth", "user", "product" etc.) If the generated client does not use tags, it will export a single class called DefaultApi
, and your app will only need a single controller.
import { apiFactory } from "../controllerFactory.ts"
import { UserApi } from "example-api-client";
export const userApi = apiFactory.createAxiosOpenApiController("user", UserApi);
There are multiple hook types available (see full docs), but for this quick start guide, here's a simple useQuery
hook for retrieving a user by ID.
export const useGetUser = (userId: string) => {
return userApi.getUser.useQuery({
cacheKey: 'userId',
params: { userId }
})
};
Here's a simple React component which uses our endpoint hook to display a user card.
import * as React from 'react';
import { useGetUser } from '../state/controllers/user';
interface IProps {
userId: string;
}
export const UserCard: React.FC<IProps> = ({ userId }) => {
const { data } = useGetUser(userId);
return (
<div>
<img src={data?.profilePic} />
<h2>{data?.name}</h2>
</div>
);
}