Skip to Content

Resource Prefetch

Schedule reusable module or data loading from visibility, proximity, idle, or explicit triggers.

useResourcePrefetch uses the resource scheduler supplied by FoldProvider to load a resource without mounting a component. It accepts a caller-owned loader, so dynamic imports and existing data caches keep their normal bundler or framework behavior.

Quick start

"use client";

import { useResourcePrefetch } from "@puzzle-ui/hooks";
import type { IdentifiedResourceDescriptor } from "@puzzle-ui/core/resources";

const chartResource = {
  id: "dashboard-chart",
  type: "component-chunk",
  priority: "low",
} satisfies IdentifiedResourceDescriptor<"component-chunk">;

const loadChart = (signal: AbortSignal) => {
  if (signal.aborted) throw new Error("Chart loading was cancelled.");
  return import("./chart");
};

function ChartPrefetchRegion() {
  const { ref, state, error, retry } = useResourcePrefetch({
    resource: chartResource,
    load: loadChart,
    strategy: "proximity",
  });

  return (
    <section ref={ref} data-resource-state={state}>
      {error ? (
        <button type="button" onClick={() => void retry()}>
          Retry chart prefetch
        </button>
      ) : (
        "Chart loads when this section approaches the viewport."
      )}
    </section>
  );
}

Prefetching an imported module may download and evaluate that module, but it does not render or mount its exported component. A later import() of the same chunk can reuse the bundler and browser module cache.

Provider and scheduler

Use the hook inside FoldProvider. Each root provider creates one SSR-safe, framework-neutral scheduler; nested providers inherit it. Passing scheduler={null} disables scheduling for that subtree, while a custom scheduler can be injected:

import { createResourceScheduler } from "@puzzle-ui/core/resources";
import { FoldProvider } from "@puzzle-ui/hooks";

<FoldProvider
  scheduler={createResourceScheduler({
    maxConcurrent: 3,
    maxPrefetchResources: 12,
  })}
>
  <Application />
</FoldProvider>;

The default scheduler permits four concurrent tasks, caps background prefetch work at three concurrent tasks to leave capacity for demand loads, queues up to 100 resources, and caps the prefetch budget at 20 unique resources. It retries only when requested (once by default) and retains up to 100 completed resource results. Critical, high, normal, and low resources are ordered in that order; per-priority queue limits can be configured with maxQueuedByPriority.

Without a provider, the hook is safe to render and reports available: false. Calling prefetch or retry without a scheduler rejects with a clear error.

Triggers and lifecycle

StrategyBehavior
proximityPrefetch when the attached target is near or inside its observer root.
visibilityPrefetch when the target intersects its observer root.
idleUse requestIdleCallback with a deadline, then a frame/timer fallback.
explicitDo not start automatically; call the returned prefetch() method.
noneDisable automatic prefetching; explicit calls remain available.

Automatic scheduling is opt-in through proximity, visibility, or idle; the default is explicit. Page-hidden or suspended documents pause pending automatic work and resume it when restored. One shared set of page and network listeners serves all active hook instances. When available, the Network Information API, Save-Data, and device-memory hints suppress lower-priority automatic work on constrained devices or connections. Explicit developer calls still pass through scheduler queue and prefetch budgets.

The returned state is registered, queued, loading, loaded, failed, or cancelled. Failed work exposes error and can be retried with retry(). cancel() cancels the current request; shared work continues while another consumer still needs it. Unmounting releases the registration and cancels work with no remaining consumers.

Resource descriptors and data

Import ResourceDescriptor, ResourceLoader, ResourcePriority, and createResourceScheduler from @puzzle-ui/core/resources. Resource types include JavaScript modules, component chunks, data, images, scripts, stylesheets, fonts, and extensible custom types. Every registered resource needs a stable id, type, and priority; an optional cacheKey, URL, metadata, or cachePolicy: "no-store" can refine its behavior.

loadingStrategy: "immediate" starts work when the resource is registered; "scheduled" waits for a scheduler request; and "on-demand" defaults this hook to explicit-only prefetching. A hook-level strategy can intentionally override that automatic trigger choice.

The loader receives an AbortSignal and may report "download" and "prepare" stages. For deferred data, wrap an existing framework loader or cache-aware request and pass the signal through; Puzzle does not introduce a second data-fetching cache or replace SSR data and route loaders.

Import the hook and its options from @puzzle-ui/hooks. Use it in a client component when a framework separates server and client modules.