swr

SWR Cursor Rules

You are an expert in SWR (stale-while-revalidate). Follow these rules:

Basic Usage

• Always define a typed fetcher: const fetcher = (url: string) => fetch(url).then(r => r.json()) as Promise
• Pass a stable key — string or array. Null/undefined/falsy key skips the request
• Destructure fully: const { data, error, isLoading, isValidating, mutate } = useSWR(key, fetcher)
• Distinguish isLoading (no data yet) from isValidating (revalidating with existing data)

Key Patterns

• Use array keys for parameterized requests: useSWR(['/api/users', page], fetcher)
• Conditional fetching: useSWR(userId ? /api/users/${userId} : null, fetcher)
• Use useSWR(() => /api/users/${userId}) — function keys throw to pause on missing deps
• Keep keys deterministic — same params = same key = shared cache

Configuration

• Set global config via SWRConfig at app root for shared fetcher and options
• Set revalidateOnFocus: false for data that rarely changes (settings, profiles)
• Use refreshInterval for polling: useSWR(key, fetcher, { refreshInterval: 5000 })
• Use dedupingInterval (default 2s) to prevent duplicate requests from multiple components

Mutations

• Use the bound mutate for local mutations: const { mutate } = useSWR(key, fetcher)
• Optimistic updates: mutate(newData, { optimisticData: newData, rollbackOnError: true, revalidate: true })
• Use useSWRMutation for triggered mutations (POST/PUT/DELETE): const { trigger } = useSWRMutation(key, sendRequest)
• Global mutate for cross-component invalidation: import { mutate } from 'swr'; mutate('/api/users')

Error Handling

• Check error before rendering data — errors can coexist with stale data
• Use onErrorRetry in config to customize retry logic (or disable for 4xx)
• Display stale data with an error banner rather than replacing content with an error page
• Set errorRetryCount to limit retries: { errorRetryCount: 3 }

Performance

• Use useSWRInfinite for paginated/infinite scroll data
• Preload data: preload(key, fetcher) on hover or route prefetch
• Use the keepPreviousData option to prevent loading flicker during key changes
• Avoid waterfalls: fetch independent data in parallel with separate useSWR calls