Registry / storage / react-native-background-downloader-queue

react-native-background-downloader-queue

library5.3.3jsnpmunverified

A React Native library (v5.3.3) that manages a queue of file downloads, persisting state across app restarts and retrying failed downloads automatically. Works in the background even after the app is killed (iOS). Builds on three peer dependencies: @kesha-antonov/react-native-background-downloader for background downloading, react-native-fs for file system operations, and @react-native-async-storage/async-storage for queue persistence. The primary differentiator is automatic resume and reconciliation: it tracks a set of URLs, downloads them sequentially, and maps remote URLs to local cached paths. Supports wifi-only downloads and lazy deletion. Ships TypeScript definitions. Release cadence is irregular.

storage

npm install react-native-background-downloader-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-BACKG

react-native-background-downloader-queue

storagejavascriptv5.3.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DownloadQueue

✓ import DownloadQueue from 'react-native-background-downloader-queue'

✗ const { DownloadQueue } = require('react-native-background-downloader-queue')

Default export only; ESM-style import with TypeScript supported.

Create a download queue, initialize it, add a URL to download, and retrieve the local or remote path for use.

import DownloadQueue from 'react-native-background-downloader-queue'; const downloader = new DownloadQueue(); await downloader.init(); await downloader.addUrl('https://example.com/file.mp3'); const path = await downloader.getAvailableUrl('https://example.com/file.mp3'); console.log(path);

Debug

Known issues

gotchaMust call init() before any other methods or queue operations will fail or be lost.

fix

Call await downloader.init() immediately after constructing DownloadQueue.

affects: >=5.0.0

breakingiOS background downloads break if extra AppDelegate step is not performed.

fix

Follow the '@kesha-antonov/react-native-background-downloader' iOS setup to add BGTaskSchedulerPermittedIdentifiers and handle completion handler in AppDelegate.m.

affects: >=5.0.0

deprecatedgetAvailableUrl returns local path if downloaded, else remote URL. Behavior changed in v4 to never return null.

fix

Ensure your code expects a string from getAvailableUrl (never null).

affects: >=4.0.0

gotchaUsing multiple domain instances with same AsyncStorage keys may cause queue state corruption.

fix

Assign unique 'domain' strings when constructing multiple DownloadQueue instances.

affects: >=5.0.0

gotchaDownloads are sequential; calling addUrl for multiple URLs queues them, does not start parallel downloads.

fix

Use separate DownloadQueue instances or the internal logic for parallel if needed (not supported by default).

affects: >=5.0.0

Errors

Common errors & fixes

Error: Could not download file: [Object object]

Network error or invalid URL; peer dependency missing

fix

Ensure all peer dependencies are installed and the URL is accessible. Check for network permissions in AndroidManifest/Info.plist.

TypeError: (0 , _reactNativeBackgroundDownloaderQueue.default) is not a function

Wrong import style in a CommonJS project

fix

Use default import: import DownloadQueue from 'react-native-background-downloader-queue'

Invariant Violation: Tried to register two views with the same name

Duplicate native module registration due to misconfigured React Native linking

fix

Run react-native link and ensure auto-linking is enabled. Check for duplicate native module registrations.

undefined is not an object (evaluating '_reactNativeAsyncStorage.default.getItem')

AsyncStorage not installed or linked correctly

fix

Install @react-native-async-storage/async-storage and run react-native link or pod install.

Upgrade

Version history

5.3.3latest on npm

Audit

Dependencies

@kesha-antonov/react-native-background-downloaderrequiredCore background download engine for iOS/Android

react-native-fsrequiredFile system operations (read, write, move files)

@react-native-async-storage/async-storagerequiredPersist download queue state across app restarts

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fivecar/react-native-background-downloader-queue ↗

packagereact-native-background-downloader-queue ↗

homepagehttps://github.com/fivecar/react-native-background-downloader-queue#readme ↗