rn-background-upload

A robust, high-performance background upload library for React Native (iOS and Android). Built with the New Architecture (Turbo Modules) for maximum efficiency and future-proof compatibility.

Features

• ✅ Background Uploads: Continue uploading files even when the app is backgrounded or killed.
• ✅ New Architecture Support: Fully compatible with Turbo Modules and Fabric.
• ✅ Multipart & Raw Uploads: Supports both standard multipart/form-data and raw binary uploads.
• ✅ Progress Notifications: Built-in support for interactive notifications on Android.
• ✅ Progress Tracking: Real-time progress updates via event emitters.
• ✅ Cancellation: Easily cancel active uploads.
• ✅ Large File Support: Designed to handle large video and image files efficiently.

Installation

npm install rn-background-upload
# or
yarn add rn-background-upload

iOS

Run pod install:

npx pod-install

Android

No additional setup is required.

Usage

1. Simple Upload

import { startUpload } from 'rn-background-upload';

const options = {
  url: 'https://myserver.com/upload',
  path: 'path/to/file.mp4',
  method: 'POST',
  type: 'multipart',
  field: 'file',
  headers: {
    'Authorization': 'Bearer ...',
  },
  notification: {
    enabled: true
  }
};

const uploadId = await startUpload(options);
console.log('Upload started with ID:', uploadId);

2. Listening for Events

We use an event subscription model compatible with React Native's new architecture.

import { useEffect } from 'react';
import { onProgress, onCompleted, onError, onCancelled } from 'rn-background-upload';

useEffect(() => {
  const progressSub = onProgress((event) => {
    if (event.id === myUploadId) {
      console.log(`Progress: ${event.progress}%`);
    }
  });

  const completeSub = onCompleted((event) => {
    console.log('Upload finished with code:', event.responseCode);
  });

  return () => {
    progressSub.remove();
    completeSub.remove();
    // ... clean up other subscriptions
  };
}, [myUploadId]);

3. API Reference

startUpload(options)

Starts a background upload. Returns a Promise<string> with the upload ID.

Options:

• url (string, required): The endpoint to upload to.
• path (string, required): The absolute path to the file.
• method (string): HTTP method (POST or PUT, default: POST).
• type (string): Upload type (multipart or raw, default: raw).
• field (string): Field name for multipart uploads (required if type is multipart).
• headers (object): Custom HTTP headers.
• parameters (object): Form data parameters (multipart only).
• notification (object): Android notification config (enabled: boolean).

cancelUpload(uploadId)

Cancels an active upload by ID. Returns Promise<boolean>.

getFileInfo(path)

Gets metadata for a file at a given path.

onProgress(callback), onCompleted(callback), onError(callback), onCancelled(callback)

Subscription methods for upload events.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library