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
```