93 lines
6.0 KiB
Markdown
93 lines
6.0 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [error-codes](./src/error-codes/error-codes.md) — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure m…
|
|
- [use-packed-audio](./src/hooks/use-packed-audio/use-packed-audio.md) — `usePackedAudio` is the audio analogue of `usePackedImage`. It binds a packed audio asset URL to a React component's li…
|
|
- [use-packed-audio](./src/hooks/use-packed-audio/use-packed-audio.md) — `usePackedAudio` is the audio analogue of `usePackedImage`. It binds a packed audio asset URL to a React component's li…
|
|
- [use-packed-font](./src/hooks/use-packed-font/use-packed-font.md) — `usePackedFont` loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
|
|
- [use-packed-font](./src/hooks/use-packed-font/use-packed-font.md) — `usePackedFont` loads a packed font asset and registers it with the document so subsequent rules referencing the suppli…
|
|
- [use-packed-image](./src/hooks/use-packed-image/use-packed-image.md) — `usePackedImage` is a thin wrapper around `usePackedResource` that pre-fills sensible defaults for image assets: cachin…
|
|
- [use-packed-image](./src/hooks/use-packed-image/use-packed-image.md) — `usePackedImage` is a thin wrapper around `usePackedResource` that pre-fills sensible defaults for image assets: cachin…
|
|
- [use-packed-resource](./src/hooks/use-packed-resource/use-packed-resource.md) — `usePackedResource` is the foundation hook of `@suaveplan/react-packer`. It binds a packed-archive virtual URL (e.g. `/…
|
|
- [use-packed-resource](./src/hooks/use-packed-resource/use-packed-resource.md) — `usePackedResource` is the foundation hook of `@suaveplan/react-packer`. It binds a packed-archive virtual URL (e.g. `/…
|
|
- [use-packed-video](./src/hooks/use-packed-video/use-packed-video.md) — `usePackedVideo` binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
|
|
- [use-packed-video](./src/hooks/use-packed-video/use-packed-video.md) — `usePackedVideo` binds a packed video asset URL to a React component's lifecycle. Unlike the image and audio variants,…
|
|
- [packed-resource-provider](./src/provider/packed-resource-provider/packed-resource-provider.md) — `PackedResourceProvider` lets a React tree explicitly inject a `PackedResourceManager` from `@suaveplan/packer-browser`…
|
|
- [packed-resource-provider](./src/provider/packed-resource-provider/packed-resource-provider.md) — `PackedResourceProvider` lets a React tree explicitly inject a `PackedResourceManager` from `@suaveplan/packer-browser`…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
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
|
|
|
|
```tsx
|
|
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/error-codes/error-codes.md)
|
|
- [`src/types/react-packer.types.md`](./src/types/react-packer.types.md)
|
|
- [`src/provider/packed-resource-provider/packed-resource-provider.md`](./src/provider/packed-resource-provider/packed-resource-provider.md)
|
|
- [`src/hooks/use-packed-resource/use-packed-resource.md`](./src/hooks/use-packed-resource/use-packed-resource.md)
|
|
- [`src/hooks/use-packed-image/use-packed-image.md`](./src/hooks/use-packed-image/use-packed-image.md)
|
|
- [`src/hooks/use-packed-audio/use-packed-audio.md`](./src/hooks/use-packed-audio/use-packed-audio.md)
|
|
- [`src/hooks/use-packed-video/use-packed-video.md`](./src/hooks/use-packed-video/use-packed-video.md)
|
|
- [`src/hooks/use-packed-font/use-packed-font.md`](./src/hooks/use-packed-font/use-packed-font.md)
|
|
|