Skip to main content

React Native Background Downloader

✨ Features​

  • 📥 Background Downloads - Downloads continue even when app is in background or terminated by the OS
  • 📤 Background Uploads - Upload files reliably in the background
  • ⏸️ Pause/Resume - Full pause and resume support on both iOS and Android
  • 🔄 Re-attach to Downloads - Reconnect to ongoing downloads after app restart
  • 📊 Progress Tracking - Real-time progress updates with customizable intervals
  • 🔒 Custom Headers - Support for authentication and custom request headers
  • 📱 Expo Support - Config plugin for easy Expo integration
  • ⚡ New Architecture - Full TurboModules support for React Native
  • 📝 TypeScript - Complete TypeScript definitions included

💡 Why?​

The Problem: Standard network requests in React Native are tied to your app's lifecycle. When the user switches to another app or the OS terminates your app to free memory, your downloads stop. For small files this is fine, but for large files (videos, podcasts, documents) this creates a frustrating user experience.

The Solution: Both iOS and Android provide system-level APIs for background file transfers:

  • iOS: NSURLSession - handles downloads in a separate process, continuing even after your app is terminated by the OS. Note: if the user explicitly force-kills the app via the App Switcher, iOS cancels all background tasks — this is an iOS system limitation that cannot be overridden
  • Android: A combination of DownloadManager for system-managed downloads, Foreground Services for pause/resume support, and MMKV for persistent state storage

The Challenge: These APIs are powerful but complex. Downloads run in a separate process, so your app might restart from scratch while downloads are still in progress. Keeping your UI in sync with background downloads requires careful state management.

This Library: @kesha-antonov/react-native-background-downloader wraps these native APIs in a simple, unified JavaScript interface. Start a download, close your app, reopen it hours later, and seamlessly reconnect to your ongoing downloads with a single function call.

💡 Use Cases​

This library is perfect for apps that need reliable file transfers:

  • 🎵 Music/Podcast Apps - Download episodes for offline listening
  • 📚 E-book Readers - Download books in the background
  • 🎬 Video Streaming - Offline video downloads
  • 📁 File Managers - Large file transfers
  • 🎮 Games - Download game assets and updates
  • 📱 Enterprise Apps - Sync large documents and media