This is set of utilities for interacting with "persisters" which save your queryClient for later use. Different persisters can be used to store your client and cache to many different storage layers.
IMPORTANT - for persist to work properly, you probably want to pass QueryClient a cacheTime value to override the default during hydration (as shown above).
If it is not set when creating the QueryClient instance, it will default to 300000 (5 minutes) for hydration, and the stored cache will be discarded after 5 minutes of inactivity. This is the default garbage collection behavior.
It should be set as the same value or higher than persistQueryClient's maxAge option. E.g. if maxAge is 24 hours (the default) then cacheTime should be 24 hours or higher. If lower than maxAge, garbage collection will kick in and discard the stored cache earlier than expected.
You can also pass it Infinity to disable garbage collection behavior entirely.
Sometimes you may make changes to your application or data that immediately invalidate any and all cached data. If and when this happens, you can pass a buster string option. If the cache that is found does not also have that buster string, it will be discarded. The following several functions accept this option:
If data is found to be any of the following:
the persister removeClient() is called and the cache is immediately discarded.
You can use this to explicitly persist the cache at the moment(s) you choose.
Runs persistQueryClientSave whenever the cache changes for your queryClient. For example: you might initiate the subscribe when a user logs-in and checks "Remember me".
You can use this to restore the cache at moment(s) you choose.
Takes the following actions:
This functionality is preserved from version 3.x.
All options available are as follows:
There are actually three interfaces available:
persistQueryClient will try to restore the cache and automatically subscribes to further changes, thus syncing your client to the provided storage.
However, restoring is asynchronous, because all persisters are async by nature, which means that if you render your App while you are restoring, you might get into race conditions if a query mounts and fetches at the same time.
Further, if you subscribe to changes outside of the React component lifecycle, you have no way of unsubscribing:
For this use-case, you can use the PersistQueryClientProvider. It will make sure to subscribe / unsubscribe correctly according to the React component lifecycle, and it will also make sure that queries will not start fetching while we are still restoring. Queries will still render though, they will just be put into fetchingState: 'idle' until data has been restored. Then, they will refetch unless the restored data is fresh enough, and initialData will also be respected. It can be used instead of the normal QueryClientProvider:
PersistQueryClientProvider takes the same props as QueryClientProvider, and additionally:
If you are using the PersistQueryClientProvider, you can also use the useIsRestoring hook alongside it to check if a restore is currently in progress. useQuery and friends also check this internally to avoid race conditions between the restore and mounting queries.
Persisters have the following interfaces:
Persisted Client entries have the following interface:
You can import these (to build a persister):
You can persist however you like. Here is an example of how to build an Indexed DB persister. Compared to Web Storage API, Indexed DB is faster, stores more than 5MB, and doesn't require serialization. That means it can readily store Javascript native types, such as Date and File.
“This course is the best way to learn how to use React Query in real-world applications.”—Tanner LinsleyCheck it out