1 Overview
I built @zl-asica/react after running into the same friction points across several React projects: hooks that quietly break on the server, ambiguous APIs that invite subtle bugs, and documentation that drifts from the code it’s supposed to describe. I framed the library as a developer-facing HCI problem—how to give React teams clear affordances around server vs. client behavior, and how to make everyday tasks like event handling, viewport checks, and storage state feel predictable instead of fragile. The result is a small set of hooks and utilities where the API surface is the interface, and types are used to shape developers’ mental models rather than just to satisfy a linter.
Design-wise, the library codifies the server–client boundary up front: DOM-dependent hooks live in the main entry, while SSR-safe utilities are exported from a separate @zl-asica/react/utils module that never touches window or document. This makes server-safe usage a first-class path instead of an afterthought of typeof window !== 'undefined' checks scattered in app code. Functions like useEventListener expose strongly-typed event maps so developers can only subscribe to valid events on valid targets, turning what is usually a runtime error into compile-time feedback. All public APIs are documented via TypeDoc-generated pages that show full signatures and source locations (“Defined in …/useArray.ts”), so behavior is inspectable and reviewable in the same way you’d inspect a UI.
On the engineering side, I built and released the library with TypeScript, GitHub Actions, and JSR. CI pipelines build and sign artifacts, run tests, and publish to JSR (with npm-compatible installs), keeping the package at a 100% JSR quality score and explicitly marking compatibility across Cloudflare Workers, Node, Bun, and browsers. Tagged releases are mirrored on Zenodo for stable academic citation, and the docs site is version-aware so people can see which API surface belongs to which release. Taken together, @zl-asica/react is less a grab-bag of hooks and more a small, opinionated toolkit for React apps that need server awareness, typed ergonomics, and documentation that behaves like a trustworthy interface for developers.
2 Selected visuals
