Installation

Packages

Package	Purpose
@hyperserve/upload	Core: hooks, state machine, validation, shared theme
@hyperserve/upload-react	Web UI: DropZone, FileList, FileItem, etc.
@hyperserve/upload-react-native	React Native UI: FilePicker, FileList, FileItem, etc.
@hyperserve/upload-adapter-hyperserve	Official Hyperserve adapter

The core package is always required. Pick the UI package for your platform, or use neither for fully headless usage.

Web (React)

npm

npm install @hyperserve/upload @hyperserve/upload-react

yarn

yarn add @hyperserve/upload @hyperserve/upload-react

pnpm

pnpm add @hyperserve/upload @hyperserve/upload-react

bun

bun add @hyperserve/upload @hyperserve/upload-react

Peer dependencies: React 18+ and React DOM 18+.

React Native

npm

npm install @hyperserve/upload @hyperserve/upload-react-native

yarn

yarn add @hyperserve/upload @hyperserve/upload-react-native

pnpm

pnpm add @hyperserve/upload @hyperserve/upload-react-native

bun

bun add @hyperserve/upload @hyperserve/upload-react-native

Peer dependencies: React 18+.

Optional native dependencies

All three are optional peer dependencies. The library gracefully degrades without them.

Package	Purpose	Without it
expo-video-metadata	maxDuration validation	Skips validation, warns once
expo-video-thumbnails	Thumbnail generation	thumbnailUri stays null
react-native-background-upload	True background upload with progress	Falls back to fetch with estimated progress

React Native setup Platform resolution, FileRef, and component API.

Hyperserve Adapter

If you are uploading to Hyperserve, install the official adapter package:

npm

npm install @hyperserve/upload-adapter-hyperserve

yarn

yarn add @hyperserve/upload-adapter-hyperserve

pnpm

pnpm add @hyperserve/upload-adapter-hyperserve

bun

bun add @hyperserve/upload-adapter-hyperserve

Hyperserve Adapter Documentation for setting up the hyperserve adapter