📄 tanstack/query/latest/docs/framework/react/plugins/createSyncStoragePersister

npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client


npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

bash

pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client


pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

bash

yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client


yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

bash

bun add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client


bun add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client

Usage
-----

Import the createSyncStoragePersister function
Create a new syncStoragePersister
Pass it to the persistQueryClient function

tsx

import { persistQueryClient } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
})
// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })

persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})


import { persistQueryClient } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
})
// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })

persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})

Retries
-------

Persistence can fail, e.g. if the size exceeds the available space on the storage. Errors can be handled gracefully by providing a retry function to the persister.

The retry function receives the persistedClient it tried to save, as well as the error and the errorCount as input. It is expected to return a new PersistedClient, with which it tries to persist again. If undefined is returned, there will be no further attempt to persist.

tsx

export type PersistRetryer = (props: {
  persistedClient: PersistedClient
  error: Error
  errorCount: number
}) => PersistedClient | undefined


export type PersistRetryer = (props: {
  persistedClient: PersistedClient
  error: Error
  errorCount: number
}) => PersistedClient | undefined

### Predefined strategies

Per default, no retry will occur. You can use one of the predefined strategies to handle retries. They can be imported from '@tanstack/react-query-persist-client':

removeOldestQuery
- will return a new PersistedClient with the oldest query removed.

tsx

const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
  retry: removeOldestQuery,
})


const localStoragePersister = createSyncStoragePersister({
  storage: window.localStorage,
  retry: removeOldestQuery,
})

API
--- ### createSyncStoragePersister

Call this function to create a syncStoragePersister that you can use later with persistQueryClient.

tsx

createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)


createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)

### Options

tsx

interface CreateSyncStoragePersisterOptions {
  /** The storage client used for setting an retrieving items from cache (window.localStorage or window.sessionStorage) */
  storage: Storage | undefined | null
  /** The key to use when storing the cache */
  key?: string
  /** To avoid spamming,
   * pass a time in ms to throttle saving the cache to disk */
  throttleTime?: number
  /** How to serialize the data to storage */
  serialize?: (client: PersistedClient) => string
  /** How to deserialize the data from storage */
  deserialize?: (cachedString: string) => PersistedClient
  /** How to retry persistence on error **/
  retry?: PersistRetryer
}


interface CreateSyncStoragePersisterOptions {
  /** The storage client used for setting an retrieving items from cache (window.localStorage or window.sessionStorage) */
  storage: Storage | undefined | null
  /** The key to use when storing the cache */
  key?: string
  /** To avoid spamming,
   * pass a time in ms to throttle saving the cache to disk */
  throttleTime?: number
  /** How to serialize the data to storage */
  serialize?: (client: PersistedClient) => string
  /** How to deserialize the data from storage */
  deserialize?: (cachedString: string) => PersistedClient
  /** How to retry persistence on error **/
  retry?: PersistRetryer
}

The default options are:

tsx

{
  key = `REACT_QUERY_OFFLINE_CACHE`,
  throttleTime = 1000,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}


{
  key = `REACT_QUERY_OFFLINE_CACHE`,
  throttleTime = 1000,
  serialize = JSON.stringify,
  deserialize = JSON.parse,
}

#### serialize and deserialize options

There is a limit to the amount of data which can be stored in localStorage. If you need to store more data in localStorage, you can override the serialize and deserialize functions to compress and decompress the data using a library like lz-string .

tsx

import { QueryClient } from '@tanstack/react-query'
import { persistQueryClient } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

import { compress, decompress } from 'lz-string'

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: Infinity } },
})

persistQueryClient({
  queryClient: queryClient,
  persister: createSyncStoragePersister({
    storage: window.localStorage,
    serialize: (data) => compress(JSON.stringify(data)),
    deserialize: (data) => JSON.parse(decompress(data)),
  }),
  maxAge: Infinity,
})


import { QueryClient } from '@tanstack/react-query'
import { persistQueryClient } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

import { compress, decompress } from 'lz-string'

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: Infinity } },
})

persistQueryClient({
  queryClient: queryClient,
  persister: createSyncStoragePersister({
    storage: window.localStorage,
    serialize: (data) => compress(JSON.stringify(data)),
    deserialize: (data) => JSON.parse(decompress(data)),
  }),
  maxAge: Infinity,
})

Edit on GitHub

persistQueryClient

createAsyncStoragePersister

Partners Become a Partner

[###### Want to Skip the Docs?

Query.gg - The Official React Query Course
\

“If you’re serious about *really* understanding React Query, there’s no better way than with query.gg”—Tanner Linsley

Learn More](https://query.gg/?s=tanstack)

scarf analytics