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%
Checklist
-
Global fetcher configured in <SWRConfig>
-
Error handling for all status codes
-
Loading states for all data fetches
-
Optimistic updates for mutations
-
Conditional fetching where appropriate
-
Stable cache keys (no render-time generation)
-
TypeScript types for all data
-
Retry logic configured
-
Focus revalidation enabled
-
Global error handler for auth failures
Reference Documentation
-
Core API
-
Global Configuration
-
Mutation