SWR

SWR is a lightweight React Hooks library for remote data fetching, created by the team behind Next.js at Vercel. The name derives from stale-while-revalidate (HTTP RFC 5861): it returns cached data first, fires the request to revalidate, and delivers the up-to-date result, keeping UIs fast and reactive.

With a single useSWR hook you get request deduplication, focus and network revalidation, polling, pagination, optimistic local mutation, smart error retry, SSR/SSG support, and React Suspense — all transport- and protocol-agnostic so it works with any async fetcher.

What You Get

• A single useSWR hook that returns data, error, isLoading, isValidating, and a bound mutate
• Built-in cache with automatic request deduplication across components sharing a key
• Automatic revalidation on focus, network reconnect, and configurable interval polling
• Optimistic local mutation and cache updates via mutate and useSWRMutation
• Specialized entry points for infinite/paginated loading, immutable data, subscriptions, and mutations

Common Use Cases

• Fetching and displaying API data in React components without manual loading/error state wiring
• Keeping dashboards and feeds fresh with focus/reconnect revalidation and polling
• Building infinite scroll and paginated lists with useSWRInfinite
• Optimistic UI updates for forms and actions using useSWRMutation and mutate

Under The Hood

Architecture — SWR is organized as a small core (src/_internal) plus thin feature entry points (src/index, src/infinite, src/immutable, src/subscription, src/mutation). The main useSWR hook in src/index/use-swr.ts subscribes to a keyed global cache through React’s useSyncExternalStore (via the use-sync-external-store shim), so many components sharing a key read one cache slot and re-render only on relevant state changes. A global state map tracks per-key revalidators, timestamps, and in-flight promises to power deduplication, while a middleware pipeline (with-middleware, middleware-preset) wraps the hook to add features like immutability and infinite loading without touching the core.

Tech Stack — Written in TypeScript (99.5% of the codebase) targeting React 16.11–19 as a peer dependency, with only two tiny runtime dependencies: dequal for deep equality and use-sync-external-store for concurrent-safe store subscription. It builds with bunchee, transpiles via SWC, and ships dual ESM/CJS plus React Server Component (react-server) bundles through the package exports map.

Code Quality — The repo has an extensive test suite: 38 entries under test/ including unit, type, and Playwright e2e directories, with focused files covering caching, error retry, focus/reconnect revalidation, suspense, concurrency, and infinite loading. Code is strictly typed, linted with oxlint and formatted with oxfmt, and husky/lint-staged enforce checks on commit. Internal utilities are small, single-purpose modules (hashing, serialization, arg normalization) that keep the core hook readable.

API Design — The public API is deliberately minimal: useSWR(key, fetcher, options) returns a typed SWRResponse and covers the common case in one line, while advanced needs are opt-in via separate imports (swr/infinite, swr/mutation, swr/immutable, swr/subscription). Being fetcher-agnostic keeps boilerplate near zero, the naming is consistent and discoverable, and full TypeScript inference plus thorough documentation at swr.vercel.app make the ramp-up gentle.