What Is SWR?

Purpose and Scope

SWR is the repository’s React Hooks library for remote data fetching. Its central promise is that a component should not have to manage every request, cache lookup, loading flag, retry, and refresh trigger by hand. Instead, the component declares the resource it wants and the asynchronous function that can load it. The library then coordinates cached data, in-flight requests, and later updates so the interface can stay responsive while still converging on fresh server state.

Sources: README.md

The name comes from the stale-while-revalidate cache invalidation strategy. In SWR’s wording, the hook first returns data from cache, treats that value as stale but immediately useful, sends a request to revalidate it, and then returns the up-to-date data when the request completes. This is the idea behind the project rather than a narrow browser cache feature: it is a user-interface data flow where old information is useful enough to render while new information is being fetched.

Sources: README.md

Stale-While-Revalidate in Practice

The practical effect is that SWR optimizes for perceived speed without giving up correctness. A user may see previously fetched profile data, project metadata, or a list page immediately, while the application asks the remote source for a newer version in the background. When the response arrives, the component receives another render with the latest data. That sequence is why the README describes SWR as providing a stream of updates that keeps the UI fast and reactive rather than forcing every view to begin from an empty loading screen.

Sources: README.md

This model is especially useful in React because rendering can be driven by current state instead of imperative request bookkeeping. The component can branch on returned values such as data, error, and loading state, while the hook owns the timing of cache reads and fetch completion. The README quick start shows the common shape: call the hook with a unique request identifier and a fetcher, render an error state if the request failed, render a loading state while no result is ready, and render the successful data once it exists.

Sources: README.md

Core Primitives

The first primitive is the key. A key identifies the request and usually looks like the API URL for the resource. Because the same key represents the same cache entry, it is the bridge between one component asking for data and another component benefiting from data already loaded elsewhere. The second primitive is the fetcher. The fetcher is any asynchronous function the application chooses, so teams can use the browser fetch API, a GraphQL client, an RPC helper, or another networking layer while still letting SWR coordinate the hook-level behavior.

Sources: README.md

The third primitive is the hook result. The quick-start example highlights data, error, and isLoading as the values a component needs to decide what to render. Before the fetcher finishes, data is absent and the loading flag is true. After the request resolves, SWR updates the data or error value, clears the loading state, and rerenders the component. That result contract is intentionally small, but it is enough to express common screens while leaving room for advanced behavior such as retries, focus revalidation, polling, pagination, mutation, and Suspense.

Sources: README.md

import useSWR from 'swr'
 
function Profile() {
  const { data, error, isLoading } = useSWR('/api/user', fetcher)
 
  if (error) return <div>failed to load</div>
  if (isLoading) return <div>loading...</div>
  return <div>hello {data.name}!</div>
}

Capabilities Built on the Model

The README positions stale-while-revalidate as the foundation for a broader feature set. Built-in cache and request deduplication prevent repeated work from becoming the default behavior. Revalidation on focus and network recovery keep data synchronized with user activity and connectivity. Polling supports near real-time experiences when servers do not push changes. Pagination and scroll position recovery extend the same cache-oriented model to lists. Local mutation and optimistic UI let the interface update immediately while the application reconciles with the remote source afterward.

Sources: README.md

SWR is also described as transport and protocol agnostic. That matters because stale-while-revalidate is not limited to REST endpoints, even though the introductory key is normally a URL. The hook only requires an identifier and an asynchronous fetcher, so the data source can be chosen by the application. This design separates SWR’s responsibilities from the network client’s responsibilities: SWR manages the cache-oriented lifecycle around React rendering, and the fetcher performs the actual remote read in whatever way the project standardizes.

Sources: README.md

Trying the Concept in the Repository

The repository includes an end-to-end Next.js site that gives contributors a concrete place to observe SWR behavior in an application shell. Its README describes the usual development-server commands and points readers to a browser URL for local testing. Although that file is a generic Next.js application README, it is still useful for this concept page because stale-while-revalidate is easiest to understand by watching a page render, refresh, and update. A local site lets readers modify a page, call API routes, and see how hook-driven state appears in a running app.

Sources: e2e/site/README.md

When experimenting, start with a simple resource and a visible render branch for loading, error, and success. Reload the page, navigate away and back, or change the API response to see why returning cached data first is valuable. The key thing to watch is not merely whether a request happens, but how the interface behaves between an old value and a new value. SWR’s value is that this intermediate period becomes a designed state of the UI rather than an accidental flicker or hand-written cache workaround.

Sources: README.md, e2e/site/README.md

Relevant Source Files

• README.md — Defines SWR as a React Hooks data-fetching library, explains the stale-while-revalidate name, lists major capabilities, and provides the introductory hook example.
• e2e/site/README.md — Describes the local Next.js E2E site workflow that readers can use as an application environment while exploring SWR behavior.

System-to-Code Mapping

Next Steps

Read the quick-start page next if you want the shortest installation-to-hook path. Continue to the stale-while-revalidate model page for a deeper lifecycle explanation, or the keys and serialization page if you want to understand how identifiers become cache entries. After that, the cache and provider, global configuration, and revalidation strategy pages explain how SWR scales the same idea across components and applications. For task-oriented examples, start with basic data fetching, global fetcher, infinite loading, and optimistic UI recipes.