Set up resumable uploads for React Native

The FastPix React Native Uploads SDK adds resumable, chunked uploads to your React Native app. It uploads large videos in chunks, retries failed chunks on its own, and resumes from the last confirmed byte after a pause or a dropped connection, so an interrupted upload continues instead of starting over. It works on both Android and iOS.

Uploads go straight from the device to FastPix, so the video bytes never pass through your own server.

Platform support

Install the SDK

Install the package with npm or your preferred package manager:

npm install @fastpix/react-native-uploads

The SDK bundles its runtime dependencies (@react-native-community/netinfo, react-native-blob-util, and axios), so there are no peer dependencies to install manually.

iOS: the native modules auto-link on React Native 0.70+. After installing the package, install the pods:

cd ios && pod install && cd ..

Android: no manual linking or extra setup is required. The native modules auto-link.

Note: The SDK depends on native modules, so it does not run in Expo Go. In an Expo project, use a development build (npx expo run:ios or npx expo run:android). For a full Expo walkthrough, see Upload videos from a React Native app.

Generate a signed upload URL

The SDK uploads to a signed URL: a pre-authorized, short-lived URL that lets the device upload directly to FastPix without exposing your API credentials in the app.

To create one, you need a valid Access Token and Secret Key. See the Basic Authentication guide for how to retrieve them. Then call the Upload media from device API to get the signed URL.

Never ship your Access Token or Secret Key in the app bundle. Create signed URLs on your backend and return only the signed URL to the device.

The service below calls the Direct Upload API and returns a signed URL. This is your backend code, not part of the SDK. It uses axios and base-64 for the Basic Auth header (npm install axios base-64); on a Node backend you can drop base-64 and use Buffer.from(...).toString("base64") instead.

import axios from "axios";
import base64 from "base-64";
const TOKEN_ID = "your_token_id";
const SECRET_KEY = "your_secret_key";
const API_BASE_URL = "https://api.fastpix.com/v1/on-demand";
export async function generateSignedUrl(metadata = { uploadedBy: "react_native_app" }) {
  const auth = `Basic ${base64.encode(`${TOKEN_ID}:${SECRET_KEY}`)}`;
  const body = {
    corsOrigin: "*",
    pushMediaSettings: {
      metadata,
      accessPolicy: "public",
      maxResolution: "1080p",
    },
  };
  const response = await axios.post(`${API_BASE_URL}/upload`, body, {
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
      Authorization: auth,
    },
  });
  const data = response.data?.data;
  if (!data?.url || !data?.uploadId) {
    throw new Error("Failed to generate signed URL");
  }
  // { url, uploadId } — pass `url` to FastPixUpload; keep `uploadId` for tracking
  return { url: data.url, uploadId: data.uploadId };
}

Upload a file

Create a FastPixUpload with the signed URL and the local file URI, then call start():

import { FastPixUpload } from "@fastpix/react-native-uploads";
const upload = new FastPixUpload({
  endpoint: "https://storage.googleapis.com/...your-signed-url...", // the signed URL
  fileUri: asset.uri, // file:// URI from your image or video picker
  chunkSize: 5 * 1024, // 5 MB (minimum allowed)
});
await upload.start();

Because endpoint also accepts an async factory (() => Promise<string>), you can plug the signed-URL generator in directly. The factory runs once when start() is called, so the URL is created fresh and your token stays on your backend:

import { FastPixUpload } from "@fastpix/react-native-uploads";
import { generateSignedUrl } from "./services/SignedUrlService";
export async function uploadVideo(fileUri) {
  const upload = new FastPixUpload({
    endpoint: async () => (await generateSignedUrl()).url,
    fileUri,
    chunkSize: 16 * 1024, // 16 MB chunks
    maxRetries: 3,
    retryDelay: 2000,
    maxFileSize: 2 * 1024 * 1024, // 2 GB limit (in KB); 0 = no limit
    enableLogs: __DEV__,
  });
  upload.on("progress", ({ percentage }) => console.log(`${percentage}%`));
  upload.on("success", () => console.log("Upload complete"));
  upload.on("error", ({ message }) => console.error(message));
  await upload.start();
  return upload; // keep the ref to pause(), resume(), or abort()
}

Configuration parameters

The FastPixUpload constructor accepts these options:

Pause, resume, and network recovery

Every chunk that finishes is confirmed by the server, so a paused or interrupted upload always continues from the last confirmed byte. Completed chunks are never re-sent.

An upload can pause in two ways:

Both cases emit a pause event with a reason ('user' or 'network'), so your UI can respond:

upload.on("progress", ({ percentage }) => console.log(`${percentage}%`));
upload.on("pause", ({ reason }) => console.log(`Paused (${reason})`));
upload.on("resume", ({ fromOffset }) => console.log(`Resumed from byte ${fromOffset}`));
upload.on("success", () => console.log("Upload complete"));
await upload.start();
// Later, from a button:
upload.pause();        // pauses immediately, keeping progress
await upload.resume(); // re-syncs the server offset, then continues

An upload you paused (reason: 'user') is not auto-resumed on reconnect. That stays under your control, so a user-paused upload never restarts on its own.

Chunk-level retry tracking

Retries are tracked per chunk, not with one global counter. Each chunk gets its own budget of maxRetries attempts with exponential back-off, so one flaky chunk cannot use up the retry allowance of the others. On a network blip, only the in-flight chunk retries, and completed chunks are never re-uploaded.

Watch it live through the chunk events:

upload.on("chunkAttempt", ({ chunkIndex, attemptNumber, totalChunkNumbers }) => {
  console.log(`Chunk ${chunkIndex}/${totalChunkNumbers} — attempt ${attemptNumber}`);
});
upload.on("chunkAttemptFailure", ({ chunkIndex, attemptNumber, error }) => {
  console.warn(`Chunk ${chunkIndex} failed (attempt ${attemptNumber}): ${error.message}`);
});
upload.on("chunkSuccess", ({ chunkIndex }) => {
  console.log(`Chunk ${chunkIndex} uploaded`);
});

Lifecycle events

Subscribe with upload.on(event, handler). Each subscription returns an unsubscribe function, which makes cleanup in React’s useEffect straightforward.

Control methods

The SDK also exposes state, progress, and stateHistory getters. The upload moves through these states:

type UploadState =
  | "IDLE"       // constructed, not started
  | "STARTED"    // start() called, preparing
  | "UPLOADING"  // actively transferring chunks
  | "PAUSED"     // paused (by user or network)
  | "RESUMED"    // transitioning back into UPLOADING
  | "FAILED"     // stopped with a non-recoverable error
  | "COMPLETED"; // all chunks uploaded

Full example: progress bar with pause, resume, and abort

A complete component wiring the lifecycle to UI controls:

import React, { useEffect, useRef, useState } from "react";
import { View, Text, Button, ActivityIndicator } from "react-native";
import { FastPixUpload } from "@fastpix/react-native-uploads";
import { generateSignedUrl } from "./services/SignedUrlService";
export function VideoUploader({ fileUri }) {
  const uploadRef = useRef(null);
  const [percentage, setPercentage] = useState(0);
  const [state, setState] = useState("IDLE");
  useEffect(() => {
    const upload = new FastPixUpload({
      endpoint: async () => (await generateSignedUrl()).url, // created lazily at start()
      fileUri,
      chunkSize: 16 * 1024, // 16 MB chunks
      maxRetries: 3,
      retryDelay: 2000,
      enableLogs: __DEV__,
    });
    uploadRef.current = upload;
    // on() returns an unsubscribe function — collect and clean up on unmount.
    const off = [
      upload.on("progress", ({ percentage }) => setPercentage(percentage)),
      upload.on("stateChange", ({ to }) => setState(to)),
      upload.on("pause", ({ reason }) =>
        console.log(reason === "network" ? "Paused — waiting for network" : "Paused by user"),
      ),
      upload.on("resume", ({ fromOffset }) => console.log(`Resumed from ${fromOffset}`)),
      upload.on("success", () => console.log("Upload complete")),
      upload.on("error", ({ message }) => console.error(message)),
    ];
    upload.start();
    return () => {
      off.forEach((unsubscribe) => unsubscribe());
      upload.abort(); // release native resources if the screen unmounts mid-upload
    };
  }, [fileUri]);
  const isUploading = state === "UPLOADING" || state === "RESUMED";
  const isPaused = state === "PAUSED";
  return (
    <View style={{ padding: 16, gap: 12 }}>
      <Text>{state} — {percentage}%</Text>
      {isUploading && <ActivityIndicator />}
      <Button title="Pause"  onPress={() => uploadRef.current?.pause()}  disabled={!isUploading} />
      <Button title="Resume" onPress={() => uploadRef.current?.resume()} disabled={!isPaused} />
      <Button title="Abort"  onPress={() => uploadRef.current?.abort()}  disabled={state === "IDLE"} />
    </View>
  );
}

Troubleshooting

Set enableLogs: true in the constructor to see detailed SDK logs while diagnosing issues, and disable it in production.

What’s next

• Upload videos from a React Native app for a full Expo walkthrough with a video picker and playback.
• Set up resumable uploads for Web for the browser SDK.
• Play your videos once FastPix has processed the upload.