Show OS: Universal Uploader – Zero-dependency, stream-based file uploading with transparent XHR fallback

Hey everyone,

I wanted to share an open-source library I’ve been developing to solve a persistent issue in frontend file ingestion: handling large-file uploads efficiently without blocking the main thread, consuming excessive client-side memory, or introducing heavy npm dependencies.

The core architecture leverages Fetch Duplex streams combined with Web Streams API to achieve constant memory usage during large file transfers. For browsers lacking full duplex stream support (such as Safari), it seamlessly switches to an automated chunked XHR fallback at runtime.

⚙️ Core Architecture & Features

Constant Memory Footprint: Streams large chunks sequentially using Fetch duplex streaming where supported.

Intelligent Runtime Fallback: Detects capabilities instantly and falls back to a robust, chunked XMLHttpRequest pipeline to ensure cross-browser compatibility (including Safari).

Resilient Lifecycle Management: Built-in hooks for pause, resume, manual abort, and automated chunk-level retries with a configurable exponential backoff algorithm.

Zero Dependencies & Tree-shakeable: Written entirely in vanilla TypeScript with no external runtime dependencies (npm install u/universal-uploader/core). The architecture is highly modular, ensuring that unused upload strategies are completely tree-shaken during compilation.

React Primitive Included: Ships with a declarative React hook that maps the entire upload lifecycle to state primitives without causing redundant re-renders.

🛠️ Why Existing Solutions Didn't Fit

Most mainstream uploading libraries either rely on heavy multi-part form encodings that require buffering files entirely into browser memory, or pull in heavy polyfill architectures that bloating the initial bundle size.

I designed this to isolate the transport layer logic via a composition-based approach, separating the stream controller from the network client. To ensure deterministic behavior, the codebase is fully covered by 127 integration/unit tests validating network failures, stream interruptions, and state transitions.

🔗 Resources

GitHub Repository:

Live Documentation & Demo: Universal Stream Uploader Demo (Note: Replace with your actual demo link URL if different)

NPM Package: u/universal-uploader/react

I would highly appreciate technical feedback regarding the public API design, potential edge cases in specific Web Stream runtimes, or architectural suggestions for the transport pipeline.

Thanks for reading!