1 Abstract
@zl-asica/react is a small, TypeScript-first library of hooks and utilities designed for production React apps that need predictable behavior across server and client. The project separates SSR-safe utilities from browser-bound hooks, ships API docs generated from types, and distributes signed builds with a 100% JSR score and multi-runtime compatibility (Cloudflare Workers, Node, Bun, browsers). Versioned releases are archived for citation.
2 Design Rationale
- Ergonomics via types. API surfaces encode intent (e.g., typed event maps in
useEventListener), reducing foot-guns and cutting boilerplate in everyday tasks like input handling, viewport checks, and storage state. - Clarity over cleverness. Each hook or helper does one thing (e.g.,
useArray,useDebouncedCallback,useIntersectionObserver), with names aligned to mental models you already use in UI work. - Provenance. Publicly hosted API references are generated from source and show file origins (e.g., “Defined in: …/useArray.ts”), making behavior auditable—useful for teaching, code reviews, and replication.
3 System Overview
Server–Client boundary. The library codifies SSR constraints up front. Hooks that rely on the DOM live on the client; SSR-safe utilities (no window/document, no DOM-lifecycle coupling) are exported under @zl-asica/react/utils. This avoids runtime checks scattered through app code and clarifies what can execute on the server.
Typed surface area. API pages show generics and precise parameter types (e.g., useEventListener<KW,KH,KM,T>), encouraging compile-time correctness for event names/targets/options.
Distribution & portability. Releases are built and signed on GitHub Actions, published to JSR (npm-compatible install), and score 100% on JSR’s quality checks. Runtime badges indicate compatibility across Cloudflare Workers, Node, Bun, and browsers.
Archival. Tagged versions are mirrored on Zenodo for stable academic citations.
4 API Surface at a Glance
- Async:
useAsync,useFetch,usePolling - DOM / viewport:
useEventListener,useInViewport,useIntersectionObserver,useHideOnScrollDown,useKeyPress,useWindowSize,useScrollPosition - State / UX:
useArray,useBoolean,useCounter,useDebounce,useDebouncedCallback,useLocalStorage,useSessionStorage,useThrottle,useTimeout,useToggle,useTheme - Utilities (SSR-safe module available): arrays/objects/dates/strings/math/DOM helpers (e.g.,
assignUUID,mapRange,mergeObjects,truncateToNearestWord,getRelativeDay).
Current docs and site list v0.7.4 at the top of the navigation.
5 Engineering Choices
- TypeDoc-generated API: Reference pages are compiled from the TypeScript source, preserving signatures and source locations (“Defined in …”). This supports code review, onboarding, and reproducible usage examples.
- Performance discipline: The project markets a “Performance-Driven” stance—keep bundles small, avoid bloat—appropriate for design-heavy sites where reader experience matters.
- Portability by default: JSR distribution provides a clean path to multi-runtime installs (npm compatibility layer), and the package page explicitly flags supported environments.
- Ecosystem visibility: The package is available under your npm scope as well, which eases discovery for teams standardizing on npm registries.
6 Example of Typed Ergonomics
Typed parameters constrain the event name to known keys (WindowEventMap / HTMLElement events) and the target to specific refs. This is a small but impactful HCI choice: the UI affordance (add a listener) matches the API affordance (pick a valid event/target), with compile-time feedback instead of runtime surprises.
7 Positioning in the Hooks Landscape
Many hook libraries focus on breadth of utilities. @zl-asica/react emphasizes server awareness, typed surfaces, and auditable docs—a useful stance for research and production websites alike. (For context, other libraries now also advertise “server-safe hooks,” suggesting a converging best practice.)
8 Citation
If you use this software in your research or projects, please cite it as follows:
BIBTEX1@software{liu_2025_15558372, 2 author = {Liu, Zhuoran}, 3 title = {@zl-asica/react}, 4 year = 2025, 5 publisher = {Zenodo}, 6 doi = {10.5281/zenodo.15475245}, 7 url = {https://doi.org/10.5281/zenodo.15475245}, 8}
Add version = {<specific version>} field for the specific version you want to exactly cited to.