0
# SWR
1
2
SWR is a React Hooks library for data fetching that implements the stale-while-revalidate caching strategy. It provides fast, lightweight, and reusable data fetching capabilities with built-in caching, request deduplication, and real-time updates.
3
4
## Package Information
5
6
- **Package Name**: swr
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install swr`
10
11
## Core Imports
12
13
```typescript
14
import useSWR, { SWRConfig, useSWRConfig, mutate, preload } from "swr";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const useSWR = require("swr");
21
const { SWRConfig, useSWRConfig, mutate, preload } = require("swr");
22
```
23
24
Specialized modules:
25
26
```typescript
27
import useSWRInfinite from "swr/infinite";
28
import useSWRImmutable from "swr/immutable";
29
import useSWRSubscription from "swr/subscription";
30
import useSWRMutation from "swr/mutation";
31
```
32
33
## Basic Usage
34
35
```typescript
36
import useSWR from "swr";
37
38
// Fetcher function
39
const fetcher = (url: string) => fetch(url).then((res) => res.json());
40
41
function Profile() {
42
const { data, error, isLoading } = useSWR("/api/user", fetcher);
43
44
if (error) return <div>Failed to load</div>;
45
if (isLoading) return <div>Loading...</div>;
46
return <div>Hello {data.name}!</div>;
47
}
48
```
49
50
## Architecture
51
52
SWR is built around several key concepts:
53
54
- **Stale-While-Revalidate**: Returns cached data first (stale), then fetches fresh data (revalidate)
55
- **Global State**: Shares cache and state across components automatically
56
- **Request Deduplication**: Multiple components using same key trigger only one request
57
- **Focus/Network Revalidation**: Automatically revalidates on window focus and network recovery
58
- **Middleware System**: Extensible architecture for custom behavior and specialized use cases
59
60
## Capabilities
61
62
### Core Data Fetching
63
64
Primary hook for data fetching with caching, revalidation, and error handling. Supports TypeScript generics for type-safe data access.
65
66
```typescript { .api }
67
function useSWR<Data = any, Error = any>(
68
key: Key,
69
fetcher?: Fetcher<Data, Key> | null,
70
config?: SWRConfiguration<Data, Error>
71
): SWRResponse<Data, Error>;
72
73
type Key = string | any[] | object | (() => string | any[] | object | null | undefined | false) | null | undefined | false;
74
75
interface SWRResponse<Data, Error> {
76
data: Data | undefined;
77
error: Error | undefined;
78
mutate: KeyedMutator<Data>;
79
isValidating: boolean;
80
isLoading: boolean;
81
}
82
```
83
84
[Core Data Fetching](./core-data-fetching.md)
85
86
### Global Configuration
87
88
Provider component for configuring SWR behavior globally across the application.
89
90
```typescript { .api }
91
interface SWRConfig {
92
(props: {
93
value?: Partial<SWRConfiguration>;
94
children: React.ReactNode;
95
}): JSX.Element;
96
defaultValue: SWRConfiguration;
97
}
98
```
99
100
[Global Configuration](./global-configuration.md)
101
102
### Infinite Loading
103
104
Hook for pagination and infinite loading scenarios with automatic page management.
105
106
```typescript { .api }
107
function useSWRInfinite<Data = any, Error = any>(
108
getKey: SWRInfiniteKeyLoader<Data>,
109
fetcher?: SWRInfiniteFetcher<Data> | null,
110
config?: SWRInfiniteConfiguration<Data, Error>
111
): SWRInfiniteResponse<Data, Error>;
112
113
interface SWRInfiniteResponse<Data, Error> {
114
data: Data[] | undefined;
115
error: Error | undefined;
116
mutate: SWRInfiniteKeyedMutator<Data>;
117
size: number;
118
setSize: (size: number | ((size: number) => number)) => Promise<Data[] | undefined>;
119
isValidating: boolean;
120
isLoading: boolean;
121
}
122
```
123
124
[Infinite Loading](./infinite-loading.md)
125
126
### Immutable Data
127
128
Hook for static data that doesn't require revalidation, with all revalidation options disabled.
129
130
```typescript { .api }
131
function useSWRImmutable<Data = any, Error = any>(
132
key: Key,
133
fetcher?: Fetcher<Data, Key> | null,
134
config?: SWRConfiguration<Data, Error>
135
): SWRResponse<Data, Error>;
136
```
137
138
[Immutable Data](./immutable-data.md)
139
140
### Real-time Subscriptions
141
142
Hook for real-time data updates through WebSockets, Server-Sent Events, or other subscription mechanisms.
143
144
```typescript { .api }
145
function useSWRSubscription<Data = any, Error = any>(
146
key: Key,
147
subscribe: SWRSubscription<Key, Data, Error>,
148
config?: SWRConfiguration<Data, Error>
149
): SWRSubscriptionResponse<Data, Error>;
150
151
interface SWRSubscriptionResponse<Data, Error> {
152
data?: Data;
153
error?: Error;
154
}
155
```
156
157
[Real-time Subscriptions](./subscriptions.md)
158
159
### Remote Mutations
160
161
Hook for handling remote mutations (POST, PUT, DELETE, PATCH) with optimistic updates and rollback support.
162
163
```typescript { .api }
164
function useSWRMutation<Data = any, Error = any, ExtraArg = never>(
165
key: Key,
166
fetcher: MutationFetcher<Data, Key, ExtraArg>,
167
config?: SWRMutationConfiguration<Data, Error, Key, ExtraArg>
168
): SWRMutationResponse<Data, Error, Key, ExtraArg>;
169
170
interface SWRMutationResponse<Data, Error, Key, ExtraArg> {
171
data: Data | undefined;
172
error: Error | undefined;
173
trigger: (arg: ExtraArg, options?: SWRMutationConfiguration<Data, Error, Key, ExtraArg>) => Promise<Data | undefined>;
174
reset: () => void;
175
isMutating: boolean;
176
}
177
```
178
179
[Remote Mutations](./mutations.md)
180
181
### Cache Management
182
183
Global functions for programmatic cache manipulation and data preloading.
184
185
```typescript { .api }
186
function mutate<Data = any>(
187
key: Key,
188
data?: Data | Promise<Data> | MutatorCallback<Data>,
189
options?: boolean | MutatorOptions<Data>
190
): Promise<Data | undefined>;
191
192
function preload<Data = any>(
193
key: Key,
194
fetcher: Fetcher<Data, Key>
195
): Data;
196
197
function unstable_serialize(key: Key): string | undefined;
198
```
199
200
[Cache Management](./cache-management.md)
201
202
## Types
203
204
### Core Configuration Types
205
206
```typescript { .api }
207
interface SWRConfiguration<Data = any, Error = any> {
208
errorRetryInterval?: number;
209
errorRetryCount?: number;
210
loadingTimeout?: number;
211
focusThrottleInterval?: number;
212
dedupingInterval?: number;
213
refreshInterval?: number;
214
refreshWhenHidden?: boolean;
215
refreshWhenOffline?: boolean;
216
revalidateOnFocus?: boolean;
217
revalidateOnMount?: boolean;
218
revalidateOnReconnect?: boolean;
219
revalidateIfStale?: boolean;
220
shouldRetryOnError?: boolean | ((err: Error) => boolean);
221
suspense?: boolean;
222
fallbackData?: Data;
223
keepPreviousData?: boolean;
224
compare?: (a: Data | undefined, b: Data | undefined) => boolean;
225
isPaused?: () => boolean;
226
use?: Middleware[];
227
onSuccess?: (data: Data, key: string, config: SWRConfiguration<Data, Error>) => void;
228
onError?: (err: Error, key: string, config: SWRConfiguration<Data, Error>) => void;
229
onErrorRetry?: (err: Error, key: string, config: SWRConfiguration<Data, Error>, revalidate: Revalidator, revalidateOpts: Required<RevalidatorOptions>) => void;
230
onLoadingSlow?: (key: string, config: SWRConfiguration<Data, Error>) => void;
231
fetcher?: Fetcher<Data, Key> | null;
232
}
233
234
type Fetcher<Data, SWRKey extends Key> = SWRKey extends () => infer Arg | null | undefined | false
235
? (arg: Arg) => Data | Promise<Data>
236
: SWRKey extends null | undefined | false
237
? never
238
: SWRKey extends infer Arg
239
? (arg: Arg) => Data | Promise<Data>
240
: never;
241
242
interface KeyedMutator<Data> {
243
(data?: Data | Promise<Data> | MutatorCallback<Data>, options?: boolean | MutatorOptions<Data>): Promise<Data | undefined>;
244
}
245
246
interface MutatorOptions<Data = any> {
247
revalidate?: boolean;
248
populateCache?: boolean | ((result: Data, currentData: Data | undefined) => Data);
249
optimisticData?: Data | ((currentData: Data | undefined) => Data);
250
rollbackOnError?: boolean | ((error: any) => boolean);
251
}
252
253
type MutatorCallback<Data> = (currentData: Data | undefined) => Data | undefined;
254
255
interface SWRGlobalConfig {
256
// Extension point for global configuration options
257
}
258
```