Rocketmakers - API SWR

@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.

Installation

Install from npm using your package manage of choice:

• npm install @rocketmakers/api-swr
• pnpm add @rocketmakers/api-swr
• yarn add @rocketmakers/api-swr

Core concepts

1. Controller factory - one created for each API, used to create a "controller" for each tag within the API client.
2. Controller - one created for each tag within the API client, used to create the endpoint hooks.
3. Endpoint hook - a hook consumed by React components, used to retrieve data, run side effects, and manage cache.

Full Documentation

Setup

• Recommended file structure
• The Provider

OpenAPI + Axios usage

• OpenAPI Controller Factory
• OpenAPI Controller

Generic API client usage (NEW!)

• Generic API client (only relevant if not using a generated OpenAPI client, otherwise see section above)
• Generic Controller Factory
• Generic Controller

Endpoint hooks

• useQuery (for GET requests)
• useMutation (for POST/PUT/PATCH/DELETE requests)
• useInfiniteQuery (for paged GET requests with infinite loading)

Complex queries

• Caching
• Paging

Advanced tools

• useApiProcessing
• useGlobalFetchWrapper

Quick start

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.

1. Wrap your app with the API SWR provider

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>;
};

2. Create a controller factory

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 { axiosOpenApiControllerFactory } from '@rocketmakers/api-swr';

export const apiFactory = axiosOpenApiControllerFactory({
  basePath: 'https://my.example.api/dev',
});

3. Create a controller

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);

4. Create an endpoint hook

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 }
  })
};

5. Consume your endpoint hook in a React component

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>
  );
}