web-data-fetching-swr

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](examples/core.md) -- Fetchers, return values, SWRConfig, key patterns
• [examples/mutations.md](examples/mutations.md) -- useSWRMutation, optimistic updates, cache invalidation
• [examples/caching.md](examples/caching.md) -- Revalidation strategies, prefetching, persistence
• [examples/pagination.md](examples/pagination.md) -- useSWRInfinite, infinite scroll, offset pagination
• [examples/conditional.md](examples/conditional.md) -- Dependent queries, auth-gated fetching
• [examples/error-handling.md](examples/error-handling.md) -- Retry config, error boundaries, network detection
• [examples/suspense.md](examples/suspense.md) -- Suspense integration, SSR fallback patterns
• [reference.md](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](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](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](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](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,