CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-tanstack--react-query-persist-client

React bindings to work with persisters in TanStack/react-query

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

TanStack React Query Persist Client

TanStack React Query Persist Client provides React-specific bindings for persisting TanStack React Query client state and cache data. It exports a PersistQueryClientProvider component that wraps the standard QueryClientProvider to automatically restore persisted query data on application startup and continuously persist query state changes during runtime.

Package Information

  • Package Name: @tanstack/react-query-persist-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @tanstack/react-query-persist-client

Core Imports

import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";

For CommonJS:

const { PersistQueryClientProvider } = require("@tanstack/react-query-persist-client");

Core persistence utilities (re-exported from core package):

import { 
  persistQueryClient,
  persistQueryClientRestore,
  persistQueryClientSave,
  persistQueryClientSubscribe,
  experimental_createQueryPersister,
  removeOldestQuery,
  PERSISTER_KEY_PREFIX
} from "@tanstack/react-query-persist-client";

Types and interfaces:

import type {
  Persister,
  PersistedClient,
  PersistQueryClientOptions,
  PersistedQueryClientRestoreOptions,
  PersistedQueryClientSaveOptions,
  PersistRetryer,
  StoragePersisterOptions,
  QueryPersister,
  AsyncStorage,
  PersistedQuery,
  MaybePromise
} from "@tanstack/react-query-persist-client";

Basic Usage

import React from 'react';
import { QueryClient } from '@tanstack/react-query';
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';

// Create a persister (example using localStorage)
const persister = {
  persistClient: (client) => {
    localStorage.setItem('queryClient', JSON.stringify(client));
  },
  restoreClient: () => {
    const stored = localStorage.getItem('queryClient');
    return stored ? JSON.parse(stored) : undefined;
  },
  removeClient: () => {
    localStorage.removeItem('queryClient');
  },
};

const queryClient = new QueryClient();

function App() {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{ persister }}
      onSuccess={() => console.log('Cache restored!')}
      onError={() => console.log('Failed to restore cache')}
    >
      <div>Your app components</div>
    </PersistQueryClientProvider>
  );
}

Architecture

The package is built around several key components:

  • PersistQueryClientProvider: React provider component that handles restoration and subscription
  • Core Persistence API: Re-exported utilities from query-persist-client-core for manual persistence operations
  • Persister Interface: Abstraction for storage implementations
  • IsRestoring Context: Provides restoration state to child components

Capabilities

React Provider Component

React provider that manages persistence lifecycle, automatically restoring cache on mount and subscribing to changes for continuous persistence.

function PersistQueryClientProvider(props: PersistQueryClientProviderProps): React.JSX.Element;

interface PersistQueryClientProviderProps extends QueryClientProviderProps {
  persistOptions: OmitKeyof<PersistQueryClientOptions, 'queryClient'>;
  onSuccess?: () => Promise<unknown> | unknown;
  onError?: () => Promise<unknown> | unknown;
}

React Provider

Core Persistence Operations

Low-level persistence functions for manual control over cache restoration, saving, and subscription management.

function persistQueryClient(props: PersistQueryClientOptions): [() => void, Promise<void>];

function persistQueryClientRestore(options: PersistedQueryClientRestoreOptions): Promise<void>;

function persistQueryClientSave(options: PersistedQueryClientSaveOptions): Promise<void>;

function persistQueryClientSubscribe(props: PersistedQueryClientSaveOptions): () => void;

Core Persistence

Persister Interface

Abstract interface for implementing custom storage solutions, with support for various storage backends.

interface Persister {
  persistClient: (persistClient: PersistedClient) => Promisable<void>;
  restoreClient: () => Promisable<PersistedClient | undefined>;
  removeClient: () => Promisable<void>;
}

interface PersistedClient {
  timestamp: number;
  buster: string;
  clientState: DehydratedState;
}

Persister Interface

Experimental Query-Level Persistence

Experimental fine-grained persistence functionality that allows per-query persistence control and storage management.

function experimental_createQueryPersister<TStorageValue = string>(
  options: StoragePersisterOptions<TStorageValue>
): QueryPersister;

Experimental Features

Retry Strategies

Built-in retry strategies for handling persistence failures and storage quota issues.

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

function removeOldestQuery(props: {
  persistedClient: PersistedClient;
  error: Error;
  errorCount: number;
}): PersistedClient | undefined;

Experimental Features

Types

type Promisable<T> = T | PromiseLike<T>;

interface PersistQueryClientOptions extends 
  PersistedQueryClientRestoreOptions,
  PersistedQueryClientSaveOptions,
  PersistQueryClientRootOptions {}

interface PersistQueryClientRootOptions {
  queryClient: QueryClient;
  persister: Persister;
  buster?: string;
}

interface PersistedQueryClientRestoreOptions extends PersistQueryClientRootOptions {
  maxAge?: number;
  hydrateOptions?: HydrateOptions;
}

interface PersistedQueryClientSaveOptions extends PersistQueryClientRootOptions {
  dehydrateOptions?: DehydrateOptions;
}

// Core TanStack Query types (from @tanstack/query-core)
interface QueryClient {
  // QueryClient interface - core query management
}

interface DehydratedState {
  mutations: Array<any>;
  queries: Array<any>;
}

interface HydrateOptions {
  // Options for hydrating dehydrated state
  shouldDehydrateQuery?: (query: any) => boolean;
  shouldDehydrateMutation?: (mutation: any) => boolean;
}

interface DehydrateOptions {
  // Options for dehydrating state for persistence
  shouldDehydrateQuery?: (query: any) => boolean;
  shouldDehydrateMutation?: (mutation: any) => boolean;
}

interface QueryClientProviderProps {
  client: QueryClient;
  children: React.ReactNode;
}

type OmitKeyof<T, K extends keyof T> = Omit<T, K>;

// Constants
const PERSISTER_KEY_PREFIX = 'tanstack-query';
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tanstack/react-query-persist-client@5.86.x
Publish Source
CLI
Badge
tessl/npm-tanstack--react-query-persist-client badge