0
# TanStack React Query Persist Client
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @tanstack/react-query-persist-client
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tanstack/react-query-persist-client`
10

11
## Core Imports
12

13
```typescript
14
import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PersistQueryClientProvider } = require("@tanstack/react-query-persist-client");
21
```
22

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

25
```typescript
26
import { 
27
  persistQueryClient,
28
  persistQueryClientRestore,
29
  persistQueryClientSave,
30
  persistQueryClientSubscribe,
31
  experimental_createQueryPersister,
32
  removeOldestQuery,
33
  PERSISTER_KEY_PREFIX
34
} from "@tanstack/react-query-persist-client";
35
```
36

37
Types and interfaces:
38

39
```typescript
40
import type {
41
  Persister,
42
  PersistedClient,
43
  PersistQueryClientOptions,
44
  PersistedQueryClientRestoreOptions,
45
  PersistedQueryClientSaveOptions,
46
  PersistRetryer,
47
  StoragePersisterOptions,
48
  QueryPersister,
49
  AsyncStorage,
50
  PersistedQuery,
51
  MaybePromise
52
} from "@tanstack/react-query-persist-client";
53
```
54

55
## Basic Usage
56

57
```typescript
58
import React from 'react';
59
import { QueryClient } from '@tanstack/react-query';
60
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
61

62
// Create a persister (example using localStorage)
63
const persister = {
64
  persistClient: (client) => {
65
    localStorage.setItem('queryClient', JSON.stringify(client));
66
  },
67
  restoreClient: () => {
68
    const stored = localStorage.getItem('queryClient');
69
    return stored ? JSON.parse(stored) : undefined;
70
  },
71
  removeClient: () => {
72
    localStorage.removeItem('queryClient');
73
  },
74
};
75

76
const queryClient = new QueryClient();
77

78
function App() {
79
  return (
80
    <PersistQueryClientProvider
81
      client={queryClient}
82
      persistOptions={{ persister }}
83
      onSuccess={() => console.log('Cache restored!')}
84
      onError={() => console.log('Failed to restore cache')}
85
    >
86
      <div>Your app components</div>
87
    </PersistQueryClientProvider>
88
  );
89
}
90
```
91

92
## Architecture
93

94
The package is built around several key components:
95

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

101
## Capabilities
102

103
### React Provider Component
104

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

107
```typescript { .api }
108
function PersistQueryClientProvider(props: PersistQueryClientProviderProps): React.JSX.Element;
109

110
interface PersistQueryClientProviderProps extends QueryClientProviderProps {
111
  persistOptions: OmitKeyof<PersistQueryClientOptions, 'queryClient'>;
112
  onSuccess?: () => Promise<unknown> | unknown;
113
  onError?: () => Promise<unknown> | unknown;
114
}
115
```
116

117
[React Provider](./react-provider.md)
118

119
### Core Persistence Operations
120

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

123
```typescript { .api }
124
function persistQueryClient(props: PersistQueryClientOptions): [() => void, Promise<void>];
125

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

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

130
function persistQueryClientSubscribe(props: PersistedQueryClientSaveOptions): () => void;
131
```
132

133
[Core Persistence](./core-persistence.md)
134

135
### Persister Interface
136

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

139
```typescript { .api }
140
interface Persister {
141
  persistClient: (persistClient: PersistedClient) => Promisable<void>;
142
  restoreClient: () => Promisable<PersistedClient | undefined>;
143
  removeClient: () => Promisable<void>;
144
}
145

146
interface PersistedClient {
147
  timestamp: number;
148
  buster: string;
149
  clientState: DehydratedState;
150
}
151
```
152

153
[Persister Interface](./persister-interface.md)
154

155
### Experimental Query-Level Persistence
156

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

159
```typescript { .api }
160
function experimental_createQueryPersister<TStorageValue = string>(
161
  options: StoragePersisterOptions<TStorageValue>
162
): QueryPersister;
163
```
164

165
[Experimental Features](./experimental-features.md)
166

167
### Retry Strategies
168

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

171
```typescript { .api }
172
type PersistRetryer = (props: {
173
  persistedClient: PersistedClient;
174
  error: Error;
175
  errorCount: number;
176
}) => PersistedClient | undefined;
177

178
function removeOldestQuery(props: {
179
  persistedClient: PersistedClient;
180
  error: Error;
181
  errorCount: number;
182
}): PersistedClient | undefined;
183
```
184

185
[Experimental Features](./experimental-features.md)
186

187
## Types
188

189
```typescript { .api }
190
type Promisable<T> = T | PromiseLike<T>;
191

192
interface PersistQueryClientOptions extends 
193
  PersistedQueryClientRestoreOptions,
194
  PersistedQueryClientSaveOptions,
195
  PersistQueryClientRootOptions {}
196

197
interface PersistQueryClientRootOptions {
198
  queryClient: QueryClient;
199
  persister: Persister;
200
  buster?: string;
201
}
202

203
interface PersistedQueryClientRestoreOptions extends PersistQueryClientRootOptions {
204
  maxAge?: number;
205
  hydrateOptions?: HydrateOptions;
206
}
207

208
interface PersistedQueryClientSaveOptions extends PersistQueryClientRootOptions {
209
  dehydrateOptions?: DehydrateOptions;
210
}
211

212
// Core TanStack Query types (from @tanstack/query-core)
213
interface QueryClient {
214
  // QueryClient interface - core query management
215
}
216

217
interface DehydratedState {
218
  mutations: Array<any>;
219
  queries: Array<any>;
220
}
221

222
interface HydrateOptions {
223
  // Options for hydrating dehydrated state
224
  shouldDehydrateQuery?: (query: any) => boolean;
225
  shouldDehydrateMutation?: (mutation: any) => boolean;
226
}
227

228
interface DehydrateOptions {
229
  // Options for dehydrating state for persistence
230
  shouldDehydrateQuery?: (query: any) => boolean;
231
  shouldDehydrateMutation?: (mutation: any) => boolean;
232
}
233

234
interface QueryClientProviderProps {
235
  client: QueryClient;
236
  children: React.ReactNode;
237
}
238

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

241
// Constants
242
const PERSISTER_KEY_PREFIX = 'tanstack-query';
243
```