npm i @hazae41/xswr
Node Package
π§
Philosophy xswr uses two new approaches compared to other data fetching libraries like swr or react-query:
- Encapsulating key+fetcher+params in a single abstraction called schema.
- Composing features with very simple hooks instead of having bloated configuration and unexpected behaviors.
π₯
Features Current features
- 100% TypeScript and ESM
- Composition-based hooks
- Very easy learning curve
- No dependency except React
- Not over-engineered (hello react-query)
- No unexpected behaviour (hello swr)
- Backend agnostic fetching (REST, GraphQL, WebSocket)
- Storage agnostic caching (new Map(), LocalStorage, IndexedDB)
- Automatic refetching
- Dependent and conditional queries
- Request deduplication, cooldown, timeout, and expiration
- Page-based and cursor-based pagination
- Exponential backoff retry
- SSR & ISR support
- Optimistic mutations
- Cancellable requests
- Automatic cancellation
- Automatic garbage collection
- Per-query persistent storage
- Out of the box IndexedDB and LocalStorage
- Out of the box store normalization
- Super natural React Suspense
- React Native support
Upcoming features
- Transport agnostic streaming (ethers.js, WebSockets, Socket.io)
- Bidirectional scrolling
π§
Installation Just install @hazae41/xswr
using your favorite package manager.
npm i @hazae41/xswr
Then, wrap your app in a CoreProvider
component.
import { CoreProvider } from "@hazae41/xswr"
function MyWrapper() {
return <CoreProvider>
<MyAwesomeApp />
</CoreProvider>
}
π§ͺ
Your first mix When using xswr and its composition-based hooks, you create a mix and only include the ingredients you want.
We'll do a request at /api/data
using JSON, display it with a loading, and automatically refetch it.
β‘οΈ
Create a fetcher It will just take an url, fetch it, and return the data.
async function fetchAsJson<T>(url: string) {
const res = await fetch(url)
const data = await res.json() as T
return { data }
}
πͺ
Create a mix Then create a mix using a query and some blocks.
function useHello() {
const query = useQuery<Hello>(`/api/hello`, fetchAsJson)
useFetch(query) // Fetch on mount and on url change
useVisible(query) // Fetch when the page becomes visible
useOnline(query) // Fetch when the browser becomes online
return query
}
π
Use it in your components function MyApp() {
const { data, error } = useHello()
if (error)
return <MyError error={error} />
if (!data)
return <MyLoading />
return <MyPage data={data} />
}
πΏ
Advanced example Last example was good, but here is the best way to use XSWR.
β‘οΈ
Making our fetcher cancellable Our fetcher was good, but this one can be aborted.
async function fetchAsJson<T>(url: string, more: FetcherMore<T>) {
const { signal } = more
const res = await fetch(url, { signal })
if (!res.ok) {
const error = new Error(await res.text())
return { error }
}
const data = await res.json() as T
return { data }
}
It also returns an error if the request failed.
π
Defining schemas Using schemas may seems boilerplate, but it will save you a lot of time later.
function getHelloSchema() {
return getSchema<Hello>("/api/hello", fetchAsJson)
}
It allows you to reuse the same set of key+fetcher+params in multiple places, including imperative code.
π§ͺ
Creating mixtures The mixtures pattern allows you to reuse the same group of blocks.
function useAutoFetchMixture(query: Query) {
useFetch(query)
useVisible(query)
useOnline(query)
}
πͺ
Mixing it Once you got a schema and a mixture, you just have to mix it.
function useHelloMix() {
const query = useSchema(getHelloSchema, [])
useAutoFetchMixture(query)
return query
}
π
Use it in your app function MyApp() {
const { data, error } = useHelloMix()
if (error)
return <MyError error={error} />
if (!data)
return <MyLoading />
return <MyPage data={data} />
}