Installation

📋 Requirements

Requirement	Version
React Native	>= 0.70.0
iOS	>= 15.1
Android	API 24+ (Android 7.0)
Expo	SDK 50+ (with config plugin)

Note: For older React Native versions (0.57.0 - 0.69.x), use version 2.x of this library.

📦 Installation

Expo Projects

Step 1: Install the package

npx expo install @kesha-antonov/react-native-background-downloader

Step 2: Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      "@kesha-antonov/react-native-background-downloader"
    ]
  }
}

Plugin Options (optional)

// app.config.js
export default {
  expo: {
    plugins: [
      ["@kesha-antonov/react-native-background-downloader", {
        mmkvVersion: "1.3.16",  // Customize MMKV version on Android
        skipMmkvDependency: true  // Skip if you want to add MMKV manually
      }]
    ]
  }
}

Option	Type	Default	Description
mmkvVersion	string	'1.3.16'	The version of MMKV to use on Android. See MMKV version comparison for details.
skipMmkvDependency	boolean	false	Skip adding MMKV dependency. Set to true if you're using react-native-mmkv to avoid duplicate class errors. The plugin auto-detects react-native-mmkv but you can use this option to explicitly skip. See MMKV version comparison.

Step 3: Rebuild your app

npx expo prebuild --clean
npx expo run:ios   # or npx expo run:android

The plugin automatically handles:

• iOS: Adding the required handleEventsForBackgroundURLSession method to AppDelegate
• Android: Adding the required MMKV dependency

---

Bare React Native Projects

Step 1: Install the package

yarn:

yarn add @kesha-antonov/react-native-background-downloader

npm:

npm install @kesha-antonov/react-native-background-downloader

Step 2: Install iOS pods

yarn:

cd ios && pod install && cd ..

npm:

cd ios && pod install && cd ..

Step 3: Configure iOS AppDelegate

React Native 0.77+ (Swift)

In your project bridging header file (e.g. ios/{projectName}-Bridging-Header.h):

#import <RNBackgroundDownloader.h>

In your AppDelegate.swift:

func application(
  _ application: UIApplication,
  handleEventsForBackgroundURLSession identifier: String,
  completionHandler: @escaping () -> Void
) {
  RNBackgroundDownloader.setCompletionHandlerWithIdentifier(identifier, completionHandler: completionHandler)
}

React Native < 0.77 (Objective-C)

In your AppDelegate.m:

#import <RNBackgroundDownloader.h>

- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler
{
  [RNBackgroundDownloader setCompletionHandlerWithIdentifier:identifier completionHandler:completionHandler];
}

Step 4: Configure Android MMKV dependency

Add MMKV to your android/app/build.gradle:

dependencies {
    implementation 'com.tencent:mmkv-shared:1.3.16'
}

Note: If you're already using react-native-mmkv in your project, skip this step — it already includes MMKV. Note that react-native-mmkv v4.x uses Margelo's fork of MMKV (io.github.zhongwuzw:mmkv) which re-adds armeabi-v7a (32-bit ARM) support that was dropped in the official MMKV 2.x release.

⚠️ armeabi-v7a (32-bit ARM) users: MMKV 2.x dropped 32-bit ABI support (since v2.0.0). If you need armeabi-v7a support and get a CMake error like No compatible library found for //mmkv/mmkv, use the MMKV 1.3.x LTS series instead — it supports both armeabi-v7a and 16KB page sizes (since v1.3.14):

dependencies {
    implementation 'com.tencent:mmkv-shared:1.3.16'
}

MMKV version comparison

Dependency	armeabi-v7a (32-bit)	arm64-v8a	16KB page size	Recommended for
com.tencent:mmkv-shared:1.3.16 (default)	✅	✅	✅ (since 1.3.14)	Most apps — broadest device coverage
com.tencent:mmkv-shared:2.x	❌	✅	✅	64-bit only apps (no legacy devices)
io.github.zhongwuzw:mmkv:2.3.0 (Margelo fork)	✅	✅	✅	Used automatically by react-native-mmkv v4.x — skip manual dependency
react-native-mmkv (already in project)	✅	✅	✅	If you already use react-native-mmkv — skip Step 4 entirely

TL;DR: Use the default 1.3.16. If you already have react-native-mmkv in your project, skip Step 4.