SWR Data Fetching Patterns

Quick Guide: SWR implements the stale-while-revalidate caching strategy: show cached data instantly, revalidate in the background. Keys must be stable (strings or stable arrays),

isLoading

is for initial fetches only (use

isValidating

for background refreshes), and all write operations go through

useSWRMutation

. The null key pattern is how you do conditional fetching -- never call hooks conditionally.

---

<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST use a stable key -- keys should NOT change on every render or you'll trigger infinite requests)

(You MUST handle isLoading vs isValidating correctly -- isLoading is true only on initial fetch with no data)

(You MUST wrap mutations in

useSWRMutation

for write operations -- NOT useSWR)

(You MUST use named constants for ALL timeout, retry, and interval values -- NO magic numbers)

(You MUST use named exports only -- NO default exports)

</critical_requirements>

---

Auto-detection: SWR, useSWR, useSWRMutation, useSWRInfinite, useSWRImmutable, SWRConfig, mutate, revalidate, fetcher, stale-while-revalidate, preload

When to use:

• Read-heavy applications with infrequent mutations
• Need lightweight bundle (~5KB gzipped)
• Simple caching with automatic revalidation
• Applications where stale-while-revalidate pattern is desired

When NOT to use:

• Complex mutation workflows requiring many lifecycle callbacks
• Need built-in request cancellation (SWR requires manual AbortController)
• Complex dependent queries needing fine-grained invalidation control

Key patterns covered:

• useSWR hook with typed fetchers and state handling
• isLoading vs isValidating distinction (the most common mistake)
• Revalidation strategies (focus, reconnect, interval, manual)
• useSWRMutation for write operations with optimistic updates
• useSWRInfinite for cursor and offset pagination
• Null key pattern for conditional fetching
• SWRConfig for global defaults and SSR fallback

Detailed Resources:

• examples/core.md -- Fetchers, return values, SWRConfig, key patterns
• examples/mutations.md -- useSWRMutation, optimistic updates, cache invalidation
• examples/caching.md -- Revalidation strategies, prefetching, persistence
• examples/pagination.md -- useSWRInfinite, infinite scroll, offset pagination
• examples/conditional.md -- Dependent queries, auth-gated fetching
• examples/error-handling.md -- Retry config, error boundaries, network detection
• examples/suspense.md -- Suspense integration, SSR fallback patterns
• reference.md -- Decision frameworks, configuration tables

---

<philosophy>

Philosophy

SWR (stale-while-revalidate) returns cached data first, then revalidates in the background. This creates fast, responsive UIs while ensuring data freshness.

Core principles:

• Stale-While-Revalidate: Show cached data immediately, update in background
• Deduplication: Multiple components using same key share one request
• Focus Revalidation: Refetch when user returns to tab
• Optimistic UI: Update UI immediately, rollback on error
• Minimal API: Simple hooks, less configuration than alternatives

Trade-offs:

• Simpler API means less control over complex mutation scenarios
• Request cancellation requires manual AbortController setup
• Less opinionated about mutations (fewer lifecycle callbacks)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Typed Fetcher

The fetcher must throw on non-OK responses. If it doesn't throw, SWR treats error bodies as valid data.

// lib/fetcher.ts
interface FetchError extends Error {
  info: unknown;
  status: number;
}

const fetcher = async <T>(url: string): Promise<T> => {
  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 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.

// 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 }

// BAD: Using isValidating as loading indicator hides cached data
if (isValidating) return <Spinner />;

// GOOD: isLoading for initial, isValidating for refresh indicator
if (isLoading) return <Spinner />;
return (
  <div>
    {isValidating && <RefreshIndicator />}
    {error && data && <Banner>Data may be outdated</Banner>}
    <Content data={data} />
  </div>
);

Why bad: Showing spinner during background revalidation hides perfectly valid cached data, defeating the purpose of stale-while-revalidate

See 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.

const ERROR_RETRY_COUNT = 3;
const ERROR_RETRY_INTERVAL_MS = 5000;
const DEDUP_INTERVAL_MS = 2000;

<SWRConfig value={{
  fetcher,
  errorRetryCount: ERROR_RETRY_COUNT,
  errorRetryInterval: ERROR_RETRY_INTERVAL_MS,
  dedupingInterval: DEDUP_INTERVAL_MS,
  keepPreviousData: true,
  fallback, // Pre-fetched data for SSR hydration
}}>
  {children}
</SWRConfig>

Why good: Eliminates config duplication across components,

fallback

prop enables SSR data hydration, nested configs allow per-section overrides

See 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()

.

import useSWRMutation from "swr/mutation";

async function createPost(
  url: string,
  { arg }: { arg: CreatePostInput },
): Promise<Post> {
  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 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.

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

// BAD: Conditional hook call (breaks Rules of Hooks)
if (!userId) return <SelectUser />;
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 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.

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<PostsResponse>(
  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 for IntersectionObserver infinite scroll, offset pagination, and filtered pagination with reset.

---

Pattern 8: Revalidation Strategies

Choose strategy based on data freshness requirements.

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 for prefetching with

preload()

, cache persistence with localStorage, and deduplication.

</patterns>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Unstable key causing infinite requests -- Object/array keys create new references each render. Use string keys or stable arrays of primitives.
• isValidating used as loading state -- Shows spinner during background refresh, hiding cached data. Use

  isLoading

  for initial load only.
• useSWR for mutations --

  useSWR

  fires on mount. Use

  useSWRMutation

  for POST/PUT/DELETE.
• Fetcher doesn't throw on error -- Non-throwing fetcher returns error body as

  data

  , error state never triggers.
• Conditional hook call --

  if (!userId) return; const { data } = useSWR(...)

  breaks Rules of Hooks. Use null key pattern.

Medium Priority Issues:

• Missing

  rollbackOnError

  with

  optimisticData

  -- Without rollback, failed mutations leave stale optimistic data in cache.

• keepPreviousData: true

  for search -- Shows stale search results for a different query. Set to

  false

  for search.

• revalidateAll: true

  with useSWRInfinite -- Refetches all loaded pages on every focus event. Disable for performance.
• Missing error retry configuration -- Default retry may not be appropriate (retries 404s, retries auth errors).
• Creating fetcher inside component -- Creates new function reference each render, breaking deduplication.

Gotchas & Edge Cases:

• null

  key stops fetching, but

  undefined

  key still fetches (gets coerced to string

  "undefined"

  )

• mutate()

  without arguments revalidates the bound key only, but global

  mutate()

  without a key filter revalidates everything

• refreshInterval: 0

  disables polling (same as omitting the option)

• revalidateOnFocus

  fires on every tab focus even if data is fresh (use

  focusThrottleInterval

  to limit)
• Multiple

  useSWR

  with same key share cache and deduplicate requests automatically

• fallback

  in

  SWRConfig

  must match exact key strings --

  /api/users/1

  and

  /api/users/1/

  are different keys

• useSWRInfinite

  revalidates all pages by default (set

  revalidateAll: false

  )
• Error objects don't serialize well for cache persistence -- use structured error types

• useSWRImmutable

  in v2.4+ properly overrides global

  refreshInterval

  settings (fixed from earlier versions)

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

(You MUST use a stable key -- keys should NOT change on every render or you'll trigger infinite requests)

(You MUST handle isLoading vs isValidating correctly -- isLoading is true only on initial fetch with no data)

(You MUST wrap mutations in

useSWRMutation

for write operations -- NOT useSWR)

(You MUST use named constants for ALL timeout, retry, and interval values -- NO magic numbers)

(You MUST use named exports only -- NO default exports)

Failure to follow these rules will cause infinite request loops, incorrect loading states, and unmaintainable code.

</critical_reminders>