SWR Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: swr for comprehensive documentation.

Setup

npm install swr

When NOT to Use This Skill

Scenario	Use Instead
Complex cache invalidation needs	`tanstack-query` for advanced features
Vue 3 applications	Composables with `useFetch` or `useAsyncData`
Client-side UI state	`zustand` or React state
GraphQL queries	`@apollo/client` or `urql`
Need offline support	`tanstack-query` with persist plugin

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Using SWR for client state	Wrong abstraction, unnecessary complexity	Use Zustand or React state
Not providing global fetcher	Repetitive code, inconsistent error handling	Configure global fetcher in `<SWRConfig>`
Mutating without revalidation	Stale data shown to users	Call `mutate()` after updates
Fetching on every render	Performance issues, too many requests	Use stable key, leverage cache
Not handling error states	Poor UX, broken UI	Always check `error` property
Using different keys for same data	Cache fragmentation, duplication	Standardize key format across app
No loading states	Bad perceived performance	Use `isLoading` or `isValidating`
Manual cache updates everywhere	Hard to maintain	Use `mutate()` with optimistic updates
Ignoring `isValidating`	Confusing UX during background refetch	Show subtle indicator when revalidating
Not using conditional fetching	Unnecessary requests	Pass `null` key when data not needed

Quick Troubleshooting

Issue	Cause	Solution
Data not updating	`revalidateOnFocus` disabled	Enable in SWRConfig or use `mutate()`
"Cannot read property of undefined"	No loading check before accessing data	Add `if (isLoading) return <Loading />`
Multiple requests for same key	No deduplication interval	Set `dedupingInterval` in config
Stale data after mutation	Not calling `mutate()`	Call `mutate(key)` or `mutate()` from hook
Memory leaks	SWR instance not cleaned up	Ensure proper component unmounting
TypeScript errors	No generic type	Use `useSWR<DataType>(key, fetcher)`
Infinite refetch loop	Key changes on every render	Use `useMemo` or stable key
401 errors not handled	No global error handler	Configure error handler in `<SWRConfig>`

Core Patterns

Basic Fetching

import useSWR from 'swr';

const fetcher = (url: string) => fetch(url).then(res => res.json());

function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading } = useSWR(`/api/users/${userId}`, fetcher);

  if (error) return <div>Failed to load</div>;
  if (isLoading) return <div>Loading...</div>;
  return <div>Hello {data.name}!</div>;
}

Global Configuration

import { SWRConfig } from 'swr';

function App() {
  return (
    <SWRConfig
      value={{
        fetcher: (url) => fetch(url).then(res => res.json()),
        revalidateOnFocus: true,
        dedupingInterval: 2000,
      }}
    >
      <MyApp />
    </SWRConfig>
  );
}

Mutation

import useSWR, { mutate } from 'swr';

function UpdateUser() {
  const { data } = useSWR('/api/user', fetcher);

  async function handleUpdate() {
    await fetch('/api/user', {
      method: 'PUT',
      body: JSON.stringify({ name: 'New Name' })
    });

    // Revalidate the cache
    mutate('/api/user');
  }

  return <button onClick={handleUpdate}>Update</button>;
}

Optimistic Updates

const { data, mutate } = useSWR('/api/user', fetcher);

async function updateUser(newData: User) {
  // Optimistic update
  mutate({ ...data, ...newData }, false);

  // Send request
  await fetch('/api/user', {
    method: 'PUT',
    body: JSON.stringify(newData)
  });

  // Revalidate
  mutate();
}

Conditional Fetching

// Only fetch if userId exists
const { data } = useSWR(userId ? `/api/users/${userId}` : null, fetcher);

Pagination

function UserList() {
  const [page, setPage] = useState(1);
  const { data, isLoading } = useSWR(`/api/users?page=${page}`, fetcher);

  return (
    <>
      {data?.users.map(user => <UserCard key={user.id} user={user} />)}
      <button onClick={() => setPage(p => p + 1)}>Next</button>
    </>
  );
}

Production Readiness

Global Configuration

import { SWRConfig } from 'swr';

const fetcher = async (url: string) => {
  const res = await fetch(url);
  if (!res.ok) {
    const error = new Error('An error occurred while fetching the data.');
    error.info = await res.json();
    error.status = res.status;
    throw error;
  }
  return res.json();
};

function App() {
  return (
    <SWRConfig
      value={{
        fetcher,
        revalidateOnFocus: true,
        revalidateOnReconnect: true,
        shouldRetryOnError: true,
        errorRetryCount: 3,
        dedupingInterval: 2000,
        focusThrottleInterval: 5000,
        onError: (error) => {
          console.error('SWR Error:', error);
          if (error.status === 401) {
            // Redirect to login
          }
        },
      }}
    >
      <MyApp />
    </SWRConfig>
  );
}

Error Handling

function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading } = useSWR<User, ApiError>(
    `/api/users/${userId}`,
    fetcher
  );

  if (error) {
    if (error.status === 404) return <NotFound />;
    if (error.status >= 500) return <ServerError />;
    return <ErrorMessage error={error} />;
  }

  if (isLoading) return <Skeleton />;

  return <UserCard user={data} />;
}

Monitoring Metrics

Metric	Target
Cache hit ratio	> 80%
Average response time	< 200ms
Revalidation frequency	Appropriate for data freshness
Error rate	< 1%

swr

SWR Core Knowledge

Setup

When NOT to Use This Skill

Anti-Patterns

Quick Troubleshooting

Core Patterns

Basic Fetching

Global Configuration

Mutation

Optimistic Updates

Conditional Fetching

Pagination

Production Readiness

Global Configuration

Error Handling

Monitoring Metrics

Checklist

Reference Documentation