Persist - LocalStorage (Experimental)

VERY IMPORTANT: This plugin is currently in an experimental stage. This means that breaking changes will happen in minor and patch releases. Use at your own risk. If you choose to rely on this in production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breakages.

Installation

This plugin comes packaged with react-query and is available under the react-query/persist-localstorage-experimental import.

Usage

Import the persistWithLocalStorage function, and pass it your QueryClient instance!

1 import { persistWithLocalStorage } from 'react-query/persist-localstorage-experimental'
2 
3 const queryClient = new QueryClient()
4 
5 persistWithLocalStorage(queryClient)

How does it work?

As you use your application:

• When your query/mutation cache is updated, it will be dehydrated and serialized into localstorage. By default, this action is throttled to happen at most every 1 second to save on potentially expensive writes to localstorage, but can be customized as you see fit.

When you reload/bootstrap your app:

• Attempts to load a previously persisted dehydrated query/mutation cache from localstorage
• If a cache is found that is older than the maxAge (which by default is 24 hours), it will be discarded. This can be customized as you see fit.

Cache Busting

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 to persistWithLocalStorage, and if the cache that is found does not also have that buster string, it will be discarded.

 persistWithLocalStorage(queryClient, { buster: buildHash })

API

persistWithLocalStorage

Pass this function a QueryClient instance to persist it to localstorage.

 persistWithLocalStorage(queryClient, options)

Options

An optional object of options:

1 interface Options {
2   /** The key to use when storing the cache to localstorage */
3   localStorageKey?: string
4   /** To avoid localstorage spamming,
5    * pass a time in ms to throttle saving the cache to disk */
6   throttleTime?: number
7   /** The max-allowed age of the cache.
8    * If a persisted cache is found that is older than this
9    * time, it will be discarded */
10   maxAge?: number
11   /** A unique string that can be used to forcefully
12    * invalidate existing caches if they do not share the same buster string */
13   buster?: string
14 }

The default options are:

1 {
2   localStorageKey = `REACT_QUERY_OFFLINE_CACHE`,
3   throttleTime = 1000,
4   maxAge = 1000 * 60 * 60 * 24, // 24 hours
5   buster = '',
6 }