Installation

Packages

Package	Purpose
@hyperserve/video-uploader	Core: hooks, state machine, validation, shared theme
@hyperserve/video-uploader-react	Web UI: DropZone, FileList, FileItem, etc.
@hyperserve/video-uploader-react-native	React Native UI: FilePicker, FileList, FileItem, etc.
@hyperserve/video-uploader-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/video-uploader @hyperserve/video-uploader-react

yarn

yarn add @hyperserve/video-uploader @hyperserve/video-uploader-react

pnpm

pnpm add @hyperserve/video-uploader @hyperserve/video-uploader-react

bun

bun add @hyperserve/video-uploader @hyperserve/video-uploader-react

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

React Native

npm

npm install @hyperserve/video-uploader @hyperserve/video-uploader-react-native

yarn

yarn add @hyperserve/video-uploader @hyperserve/video-uploader-react-native

pnpm

pnpm add @hyperserve/video-uploader @hyperserve/video-uploader-react-native

bun

bun add @hyperserve/video-uploader @hyperserve/video-uploader-react-native

Peer dependencies: React 18+.

Optional native dependencies

These 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
expo-video	In-app playback of ready videos	Falls back to the thumbnail image
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/video-uploader-adapter-hyperserve

yarn

yarn add @hyperserve/video-uploader-adapter-hyperserve

pnpm

pnpm add @hyperserve/video-uploader-adapter-hyperserve

bun

bun add @hyperserve/video-uploader-adapter-hyperserve

Hyperserve Adapter Documentation for setting up the hyperserve adapter

Local development against a checkout

When developing against a local clone of universal-video-uploader (for example, to test a fix before publishing), npm github: URLs do not target subdirectories of a monorepo. Use a file: reference in your consumer app’s package.json instead:

{
  "dependencies": {
    "@hyperserve/video-uploader": "file:../path/to/universal-video-uploader/packages/core",
    "@hyperserve/video-uploader-react": "file:../path/to/universal-video-uploader/packages/react",
    "@hyperserve/video-uploader-adapter-hyperserve": "file:../path/to/universal-video-uploader/packages/upload-adapter-hyperserve"
  }
}

Run bun build (or npm run build) inside the cloned repo before installing. The file: reference resolves to the package’s built output, so re-run the build after each change.

For published preview builds (for example, from a pull request), use pkg.pr.new URLs.