useSWRSubscription

Purpose and Scope

useSWRSubscription is the SWR entrypoint for wiring an SWR resource to an external source that pushes updates over time. Instead of asking a fetcher to request a value once, the hook accepts a subscriber function that connects to a data source, reports each new value through a callback, and returns an unsubscribe function for cleanup. This makes it the right API for sources such as sockets, event emitters, browser APIs, collaborative state channels, or any adapter where the data producer controls when updates arrive.

Sources: src/subscription/index.ts, src/subscription/types.ts

SWR already frames the library as a React Hooks data-fetching system that keeps interfaces fast and reactive by returning cached data, revalidating, and delivering a stream of data updates. The subscription hook fits that broader model by using the same cache and mutation machinery as the main hook while replacing the normal request lifecycle with a continuous subscription lifecycle. Readers who already know useSWR should think of this API as a cache-backed bridge from external event streams into SWR state, not as a separate state container.

Sources: README.md, src/subscription/index.ts

The implementation marks the hook as experimental in its public comment, so application code should treat the exact API as subject to future change. Even with that caveat, the source defines a clear contract today: call the hook with a key, a subscription function, and optional SWR configuration; receive a response with data and error; call next from the external subscription whenever the source emits either a value or a failure; and always return a cleanup function. That cleanup requirement is enforced at runtime, not merely described by TypeScript.

Sources: src/subscription/index.ts, src/subscription/types.ts

Relevant Source Files

src/subscription/types.ts — Defines the public TypeScript contract for subscription options, subscriber functions, hook responses, and the SWRSubscriptionHook call signature.
src/subscription/index.ts — Implements the subscription middleware, the default useSWRSubscription export, key prefixing, cache-scoped reference counting, update propagation, and cleanup validation.
README.md — Provides the repository-level description of SWR as a React Hooks data-fetching library with cache, real-time updates, and reactive streams of data.
subscription/package.json — Describes the published subpackage metadata for the subscription entrypoint, including CommonJS, ES module, and declaration file targets.
e2e/site/README.md — Documents how the repository’s Next.js end-to-end site can be started for browser-oriented validation work.

Public API Reference

The default import is useSWRSubscription from the swr/subscription subpath. Its type is exported as SWRSubscriptionHook, which is generic over the data type, error type, and key type. The call shape is a hook call with three inputs: a key, a subscriber, and optional SWR configuration. The response is intentionally small: it exposes optional data and optional error. Unlike the primary useSWR return object, the subscription response type in the supplied source does not include loading flags, validation flags, or a bound mutate function.

Sources: src/subscription/types.ts, src/subscription/index.ts

The subscriber function receives the resolved key argument and an options object containing next. Calling next with an error records that error in the SWR cache entry. Calling next with no error and a data value clears the previous error and writes the new value by delegating to SWR mutation without triggering revalidation. The data parameter can also be a MutatorCallback, so a subscription can compute its next value from the previous cached value when the event source only sends a patch or increment rather than a complete replacement.

Sources: src/subscription/types.ts, src/subscription/index.ts

import useSWRSubscription from 'swr/subscription'
 
function LiveWidget({ roomId }) {
  const { data, error } = useSWRSubscription(
    () => roomId ? ['/rooms', roomId] : null,
    (key, { next }) => {
      const unsubscribe = dataSource.subscribe(key, (err, value) => {
        next(err, value)
      })
      return unsubscribe
    }
  )
 
  if (error) return <p>subscription failed</p>
  return <pre>{JSON.stringify(data)}</pre>
}

The key type follows SWR’s normal key family, but the subscription type applies conditional inference so the subscriber receives the useful argument form. When the key is a function that returns an argument or a disabled value, the subscriber is typed with the returned argument. When the key is directly null, undefined, or false, the subscriber type becomes unusable because there is no active subscription to establish. For ordinary keys, the subscriber receives that key argument directly. This mirrors the runtime behavior where serialization may produce no cache key, in which case the effect exits without subscribing.

Sources: src/subscription/types.ts, src/subscription/index.ts

Runtime Flow and Cache Integration

At runtime, the exported hook is assembled by wrapping the normal SWR hook with a subscription middleware. The middleware serializes the user key into a stable cache key and argument payload, prefixes the cache key with a subscription marker, and calls the next SWR hook with that subscription key and a null fetcher. The prefix is an important implementation detail because it keeps subscription cache entries from colliding with ordinary resources that happen to use the same user-facing key. The null fetcher also communicates that updates are driven by the external subscription rather than by an SWR fetcher.