Preload Utility

Purpose

The Preload Utility addresses the challenge of avoiding redundant data fetches when a resource is likely to be needed soon but is not yet actively requested by a component. It enables preloading data ahead of time and caching the fetch result, so that subsequent component rendering can instantly consume the cached data without triggering another fetch. This reduces loading waterfalls and improves perceived performance by ensuring that once a component mounts, it does not duplicate expensive fetch calls already initiated during preloading.

Within the broader data preloading topic, this utility specifically focuses on the function that initiates and caches preloads and the middleware that seamlessly integrates preloaded results into the SWR lifecycle.

Functionality

Core Preloading Logic

The utility exposes a preload function that accepts a cache key and a fetcher function. It serializes the key to a string form and checks a dedicated preload cache to determine if a preload request for that key is already in progress or resolved. If so, the existing Promise or data is returned immediately, ensuring idempotent behavior where multiple preload calls for the same key do not trigger duplicate fetches.

If no preload exists, the fetcher is invoked with the deserialized arguments, and the Promise returned is stored in the preload cache keyed by the serialized key. This Promise is then returned to the caller, representing the ongoing preload operation.

if (PRELOAD[key]) return PRELOAD[key]

const req = fetcher(fnArg)
PRELOAD[key] = req
return req

Middleware Integration

To make preloading transparent when using SWR hooks, the utility provides a middleware function. This middleware wraps the fetcher passed to SWR hooks and intercepts fetch requests.

• It serializes the SWR key and checks the preload cache for a matching cached preload Promise.

• If a preload Promise exists, it immediately returns the cached Promise and clears the preload entry to avoid repeated reuse.

• If not found, it falls back to executing the original fetcher.

This design ensures that when a component calls useSWR (or related hooks), it can consume preloaded data if available, avoiding duplicate network requests.

const req = PRELOAD[key]
if (isUndefined(req)) return fetcher_(...args)
delete PRELOAD[key]
return req

Special Case: Infinite Loading

The middleware skips this preload cache interception for keys with the infinite loading prefix, delegating preload handling to the infinite loading logic to prevent conflicts.

Relationship with Parent Topic and Other Subtopics

The Preload Utility forms the foundational mechanism enabling data preloading by managing the preload cache and fetch execution. It complements the broader Data Preloading topic by:

• Providing the primitive preload function for manual or automated preloading of data.

• Offering middleware that injects preloaded results seamlessly into SWR hooks.

Other subtopics under Data Preloading, such as the Preload Middleware, build upon this utility to create a transparent developer experience where preloaded data is utilized automatically without requiring explicit preload consumption logic in components.

By integrating at the middleware layer, it enhances the core SWR data fetching behavior, working harmoniously with caching, suspense, and revalidation features. This utility also interoperates cleanly with other modules like infinite loading and mutation by respecting their specific fetcher behaviors and key conventions.

Diagram

flowchart TD
  A[Call preload(key, fetcher)] --> B{Is preload cached for key?}
  B -- Yes --> C[Return cached Promise]
  B -- No --> D[Invoke fetcher with args]
  D --> E[Store Promise in preload cache]
  E --> F[Return Promise]

  subgraph Middleware flow during useSWR fetch
    G[useSWR calls fetcher(key)] --> H{Preload cache has Promise?}
    H -- Yes --> I[Return cached Promise]
    H -- No --> J[Call original fetcher]
    I --> K[Delete preload cache entry]
  end

This flowchart illustrates how the preload function caches fetch promises keyed by serialized keys, and how the middleware integrates this cache to serve preloaded data within the SWR hook fetch process, ensuring fetch deduplication and smooth data preloading.