use-web-kit

use-web-kit

Zero-dependency, frame-perfect performance toolkit for React 19 and Next.js 15.

14 hooks. Zero dependencies. One philosophy: never let a hook library become the bottleneck in your production application.

use-web-kit replaces naive per-component observer patterns with global singletons, RAF-batched state updates, and React 19 ref callback cleanup. Built for senior engineers shipping enterprise-scale React and Next.js applications.

Why use-web-kit

Most hook libraries create one IntersectionObserver per component, one BroadcastChannel per instance, one addEventListener per render. At scale, these patterns cause measurable performance degradation.

use-web-kit enforces four non-negotiable constraints:

Constraint	How
Zero memory leaks	React 19 ref cleanup, ref-counted singletons, explicit disposal of timers, Blob URLs, and channels
O(1) observer cost	Single global IntersectionObserver shared by all components
No render thrashing	useReducer for multi-value state, requestAnimationFrame batching for intersection events
Perfect SSR hydration	useSyncExternalStore with stable server snapshots for all BOM and storage hooks

Hooks

DOM and Rendering

• useSmartIntersection -- Global singleton observer with RAF batching and startTransition support
• useIntersection -- Per-instance observer pool with configurable rootMargin and threshold
• useMediaControls -- Unidirectional state for <audio> and <video> elements

Concurrency

• useWorkerPool -- Ephemeral Web Worker pool from pure functions via Blob URL serialization
• useIdleQueue -- Background task scheduling via requestIdleCallback
• useAdaptivePolling -- Interval polling that adapts to page visibility

State and Persistence

• useDebouncedStorage -- Hydration-safe storage with debounced writes and cross-tab sync
• useStorage -- Basic localStorage/sessionStorage persistence
• useBroadcastState -- Cross-tab state sharing via ref-counted BroadcastChannel singleton

Pipelines

• useEventPipeline -- Composable event processing with AbortController cancellation
• useActionPipeline -- FormData processing for React 19 <form action> and Server Actions

Browser Object Model

• useNetworkStatus -- Online/offline state and Network Information API telemetry
• usePageLifecycle -- Page visibility, focus, and frozen state tracking
• usePermission -- Permissions API monitoring with legacy fallbacks

Quick Start

import { useSmartIntersection, useWorkerPool, useDebouncedStorage } from 'use-web-kit';

// Lazy-load images with a single global observer
function LazyImage({ src }: { src: string }) {
  const { ref, isIntersecting } = useSmartIntersection({ lowPriority: true });
  return <img ref={ref} src={isIntersecting ? src : undefined} />;
}

// Offload computation to a Web Worker
const sort = (arr: number[]) => [...arr].sort((a, b) => a - b);

function SortButton({ data }: { data: number[] }) {
  const { run, isRunning } = useWorkerPool(sort, { maxWorkers: 2 });
  return (
    <button disabled={isRunning} onClick={async () => {
      const [promise] = run(data);
      console.log(await promise);
    }}>
      Sort off-thread
    </button>
  );
}

// Persistent state with instant UI and debounced disk writes
function DraftEditor() {
  const { value, setValue, flush } = useDebouncedStorage('draft', '', { debounceMs: 500 });
  return <textarea value={value} onChange={e => setValue(e.target.value)} onBlur={flush} />;
}

Installation

npm install use-web-kit

Architecture

src/
  bom/          -- useNetworkStatus, usePageLifecycle, usePermission
  concurrency/  -- useWorkerPool, useIdleQueue, useAdaptivePolling
  dom/          -- useSmartIntersection, useIntersection, useMediaControls
  pipelines/    -- useEventPipeline, useActionPipeline
  state/        -- useDebouncedStorage, useStorage, useBroadcastState
  core/         -- shared TypeScript interfaces

Documentation

• Full API Reference -- every hook, every option, every return value
• Usage and Best Practices -- patterns, migration, Next.js tips
• Performance Architecture -- singletons, RAF batching, memory safety

Contributing

See CONTRIBUTING.md.

License

MIT

DEVELOPED BY TANUSH