=> {
const response = await fetch(url);
if (!response.ok) {
const error = new Error("Fetch failed") as FetchError;
error.info = await response.json().catch(() => null);
error.status = response.status;
throw error;
}
return response.json();
};
export { fetcher };
export type { FetchError };
```
**Why good:** Throws on error (required for SWR error state to work), attaches status for conditional handling, typed error enables downstream type narrowing
See [examples/core.md](examples/core.md) for axios, GraphQL, and multi-argument fetcher variants.
---
### Pattern 2: isLoading vs isValidating
The most common SWR mistake. `isLoading` is true only on initial fetch with no data. `isValidating` is true during any in-flight request.
```typescript
// State combinations:
// Initial load: { data: undefined, isLoading: true, isValidating: true }
// Success: { data: T, isLoading: false, isValidating: false }
// Revalidating: { data: T, isLoading: false, isValidating: true }
// Error (no data): { error: Error, isLoading: false, isValidating: false }
// Error (has data): { data: T, error: Error, isLoading: false }
```
```typescript
// BAD: Using isValidating as loading indicator hides cached data
if (isValidating) return ;
// GOOD: isLoading for initial, isValidating for refresh indicator
if (isLoading) return ;
return (
{isValidating && }
{error && data && Data may be outdated}
);
```
**Why bad:** Showing spinner during background revalidation hides perfectly valid cached data, defeating the purpose of stale-while-revalidate
See [examples/core.md](examples/core.md) for full state handling with error + stale data combinations.
---
### Pattern 3: SWRConfig Global Defaults
Centralize fetcher, retry, and revalidation settings. Nested SWRConfig overrides parent config.
```typescript
const ERROR_RETRY_COUNT = 3;
const ERROR_RETRY_INTERVAL_MS = 5000;
const DEDUP_INTERVAL_MS = 2000;
{children}
```
**Why good:** Eliminates config duplication across components, `fallback` prop enables SSR data hydration, nested configs allow per-section overrides
See [examples/core.md](examples/core.md) for full provider setup and nested config override patterns.
---
### Pattern 4: useSWRMutation for Writes
Never use `useSWR` for mutations. `useSWR` fires on mount -- `useSWRMutation` fires on demand via `trigger()`.
```typescript
import useSWRMutation from "swr/mutation";
async function createPost(
url: string,
{ arg }: { arg: CreatePostInput },
): Promise {
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(arg),
});
if (!response.ok) throw new Error("Failed to create post");
return response.json();
}
const { trigger, isMutating, error, reset } = useSWRMutation(
"/api/posts",
createPost,
);
await trigger({ title, content });
```
**Why good:** `trigger()` gives explicit control over when mutation fires, `isMutating` provides loading state, `reset` clears error state, separate from useSWR keeps read/write concerns apart
See [examples/mutations.md](examples/mutations.md) for optimistic updates, cache invalidation, and `populateCache` patterns.
---
### Pattern 5: Optimistic Updates with Rollback
Update UI immediately while mutation is in-flight. Rollback on error.
```typescript
const { trigger } = useSWRMutation(`/api/todos/${todo.id}`, toggleTodo, {
optimisticData: (currentData: Todo) => ({
...currentData,
completed: !currentData.completed,
}),
rollbackOnError: true,
revalidate: true,
});
```
**Why good:** `optimisticData` shows instant feedback, `rollbackOnError` ensures consistency on failure, `revalidate: true` syncs with server after success
See [examples/mutations.md](examples/mutations.md) for list-level optimistic updates and `populateCache` for skipping revalidation.
---
### Pattern 6: Null Key for Conditional Fetching
Pass `null` as the key to skip the request. Never call hooks conditionally.
```typescript
// BAD: Conditional hook call (breaks Rules of Hooks)
if (!userId) return ;
const { data } = useSWR(`/api/users/${userId}`, fetcher);
// GOOD: Null key prevents request without conditional hook
const { data } = useSWR(userId ? `/api/users/${userId}` : null, fetcher);
// GOOD: Dependent queries -- second waits for first
const { data: user } = useSWR(`/api/users/${userId}`, fetcher);
const { data: posts } = useSWR(user ? `/api/users/${user.id}/posts` : null, fetcher);
```
**Why good:** Hook always called (no Rules of Hooks violation), null key is idiomatic SWR pattern, enables data cascades for dependent queries
See [examples/conditional.md](examples/conditional.md) for auth-gated, feature-flag, and complex multi-condition patterns.
---
### Pattern 7: useSWRInfinite for Pagination
The `getKey` function receives page index and previous page data. Return `null` to stop.
```typescript
import useSWRInfinite from "swr/infinite";
const PAGE_SIZE = 20;
const getKey = (pageIndex: number, previousPageData: PostsResponse | null) => {
if (previousPageData && !previousPageData.hasMore) return null; // End
if (pageIndex === 0) return `/api/posts?limit=${PAGE_SIZE}`;
return `/api/posts?limit=${PAGE_SIZE}&cursor=${previousPageData?.nextCursor}`;
};
const { data, size, setSize, isLoading } = useSWRInfinite(
getKey,
fetcher,
{
revalidateFirstPage: false,
},
);
const posts = data?.flatMap((page) => page.posts) ?? [];
const isReachingEnd = data?.[data.length - 1]?.hasMore === false;
```
**Why good:** `getKey` returning null stops fetching, `flatMap` flattens pages, `revalidateFirstPage: false` prevents refetching all pages on focus
See [examples/pagination.md](examples/pagination.md) for IntersectionObserver infinite scroll, offset pagination, and filtered pagination with reset.
---
### Pattern 8: Revalidation Strategies
Choose strategy based on data freshness requirements.
```typescript
const POLL_INTERVAL_MS = 10 * 1000;
// Real-time: polling
useSWR(key, fetcher, {
refreshInterval: POLL_INTERVAL_MS,
refreshWhenHidden: false,
});
// Default: revalidate on focus/reconnect (enabled by default)
useSWR(key, fetcher, { revalidateOnFocus: true, revalidateOnReconnect: true });
// Static: disable all revalidation
useSWR(key, fetcher, {
revalidateOnFocus: false,
revalidateOnReconnect: false,
revalidateIfStale: false,
});
// Shorthand for static: useSWRImmutable
import useSWRImmutable from "swr/immutable";
useSWRImmutable(key, fetcher);
```
**Why good:** Different strategies for different freshness needs, `useSWRImmutable` is cleaner than disabling all options manually, `refreshWhenHidden: false` prevents polling when tab is hidden
See [examples/caching.md](examples/caching.md) for prefetching with `preload()`, cache persistence with localStorage, and deduplication.