suaveplan/packages/foundation/data/react-packer/README.md

@suaveplan/react-packer - React 19 companion for @suaveplan/packer-browser — usePackedResource, usePackedImage, usePackedAudio, usePackedVideo, usePackedFont hooks plus PackedResourceProvider context. Consumes a real PackedResourceManager; React is a peer dep so non-React consumers never pay the cost.

React 19 companion for @suaveplan/packer-browser. Ships usePackedResource, usePackedImage, usePackedAudio, usePackedVideo, and usePackedFont hooks plus a PackedResourceProvider context, so applications can consume packed asset archives from React components without @suaveplan/packer-browser having to ship React as a runtime dep.

Documentation tree

• error-codes — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
  • error-codes — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
• use-packed-audio — usePackedAudio is the audio analogue of usePackedImage. It binds a packed audio asset URL to a React component's li…
  • use-packed-audio — usePackedAudio is the audio analogue of usePackedImage. It binds a packed audio asset URL to a React component's li…
• use-packed-font — usePackedFont loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
  • use-packed-font — usePackedFont loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
• use-packed-image — usePackedImage is a thin wrapper around usePackedResource that pre-fills sensible defaults for image assets: cachin…
  • use-packed-image — usePackedImage is a thin wrapper around usePackedResource that pre-fills sensible defaults for image assets: cachin…
• use-packed-resource — usePackedResource is the foundation hook of @suaveplan/react-packer. It binds a packed-archive virtual URL (e.g. `/…
  • use-packed-resource — usePackedResource is the foundation hook of @suaveplan/react-packer. It binds a packed-archive virtual URL (e.g. `/…
• use-packed-video — usePackedVideo binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
  • use-packed-video — usePackedVideo binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
• packed-resource-provider — PackedResourceProvider lets a React tree explicitly inject a PackedResourceManager from @suaveplan/packer-browser…
  • packed-resource-provider — PackedResourceProvider lets a React tree explicitly inject a PackedResourceManager from @suaveplan/packer-browser…

Install

bun add @suaveplan/react-packer @suaveplan/packer-browser

react and react-dom (≥ 19.0.0) are peer dependencies — the package does not bundle them.

Quick start

import { createPackedResourceManager } from "@suaveplan/packer-browser";
import { PackedResourceProvider, usePackedImage } from "@suaveplan/react-packer";

const manager = createPackedResourceManager();

function App() {
    return (
        <PackedResourceProvider value={{ manager }}>
            <Logo />
        </PackedResourceProvider>
    );
}

function Logo() {
    const { url, loading, error } = usePackedImage("/assets/logo.packed");
    if (loading) return <div className="logo logo--loading" />;
    if (error !== null) return <div className="logo logo--error" />;
    return url !== null ? <img alt="logo" src={url} /> : null;
}

If you do not mount a PackedResourceProvider, hooks fall back to the singleton at @suaveplan/packer-browser/singleton. Adopters that prefer zero-config get a working manager for free; adopters that want explicit lifecycle (tests, SSR, multi-tenant apps) mount a provider and skip the singleton entirely.

Features

• Five hooks: usePackedResource (generic), usePackedImage, usePackedAudio, usePackedVideo, usePackedFont.
• React 19 context provider for explicit PackedResourceManager and MessageResolver injection.
• AbortSignal honored throughout — pre-aborted signals short-circuit, unmount cancels the in-flight load, and changing the packed URL aborts the previous one.
• Stable error registry — REACT_PACKER_CODES + ReactPackerError branded subclass over @suaveplan/error.
• cleanup releases the cached entry on unmount so the manager's LRU can evict.

Modules

• src/error-codes/error-codes.md
• src/types/react-packer.types.md
• src/provider/packed-resource-provider/packed-resource-provider.md
• src/hooks/use-packed-resource/use-packed-resource.md
• src/hooks/use-packed-image/use-packed-image.md
• src/hooks/use-packed-audio/use-packed-audio.md
• src/hooks/use-packed-video/use-packed-video.md
• src/hooks/use-packed-font/use-packed-font.md