@capgo/capacitor-downloader

Overview

The Capacitor Downloader plugin provides powerful file download capabilities with support for background downloads, progress tracking, and comprehensive download management. This plugin enables robust file downloading with pause/resume functionality and detailed progress monitoring.

⚠️ Work in Progress: This plugin is currently under development and not yet ready for production use.

Background downloads

Continue downloads when app is backgrounded 📥

Progress tracking

Real-time download progress and status monitoring 📊

Download control

Pause, resume, and stop downloads dynamically ⏯️

Network options

Configure network preferences and priorities 📶

Installation

npm install @capgo/capacitor-downloader
npx cap sync

Core API Methods

Download Management

• download(options) - Start a new file download
• pause(id) - Pause an ongoing download
• resume(id) - Resume a paused download
• stop(id) - Stop and cancel a download
• checkStatus(id) - Get current download status

File Operations

• getFileInfo(path) - Retrieve file information and metadata

Download Configuration

interface DownloadOptions {
  id: string;                    // Unique download identifier
  url: string;                   // Download source URL
  destination: string;           // Local save path
  headers?: Record<string, string>; // Custom HTTP headers
  network?: 'cellular' | 'wifi-only'; // Network restrictions
  priority?: 'high' | 'normal' | 'low'; // Download priority
}

Event Listeners

The plugin provides comprehensive event handling:

• downloadProgress - Track real-time download progress
• downloadCompleted - Handle successful download completion
• downloadFailed - Handle download errors and failures

Usage Example

import { Downloader } from '@capgo/capacitor-downloader';

// Start a download
const downloadId = 'my-download-001';
await Downloader.download({
  id: downloadId,
  url: 'https://example.com/large-file.zip',
  destination: '/downloads/large-file.zip',
  headers: {
    'Authorization': 'Bearer token123'
  },
  network: 'wifi-only',
  priority: 'high'
});

// Listen for progress updates
Downloader.addListener('downloadProgress', (data) => {
  console.log(`Download ${data.id}: ${data.progress}% complete`);
  console.log(`Downloaded: ${data.bytesDownloaded}/${data.totalBytes} bytes`);
});

// Handle completion
Downloader.addListener('downloadCompleted', (data) => {
  console.log(`Download completed: ${data.id}`);
  console.log(`File saved to: ${data.path}`);
});

// Handle errors
Downloader.addListener('downloadFailed', (error) => {
  console.error(`Download failed: ${error.id}`, error.message);
});

// Pause a download
await Downloader.pause(downloadId);

// Resume the download
await Downloader.resume(downloadId);

// Check download status
const status = await Downloader.checkStatus(downloadId);
console.log('Download status:', status);

// Stop the download
await Downloader.stop(downloadId);

Network Configuration

WiFi-Only Downloads

await Downloader.download({
  id: 'large-file',
  url: 'https://example.com/video.mp4',
  destination: '/downloads/video.mp4',
  network: 'wifi-only' // Restricts to WiFi networks only
});

Priority Management

// High priority download
await Downloader.download({
  id: 'urgent-update',
  url: 'https://example.com/update.zip',
  destination: '/downloads/update.zip',
  priority: 'high'
});

Download States

Downloads can be in various states:

• Pending: Queued for download
• Running: Currently downloading
• Paused: Temporarily stopped
• Completed: Successfully finished
• Failed: Encountered an error
• Stopped: Manually cancelled

File Information

// Get file details
const fileInfo = await Downloader.getFileInfo('/downloads/my-file.pdf');
console.log('File size:', fileInfo.size);
console.log('Last modified:', fileInfo.lastModified);
console.log('MIME type:', fileInfo.mimeType);

Best Practices

• Use unique download IDs to avoid conflicts
• Implement proper error handling for network failures
• Consider storage space before starting large downloads
• Use WiFi-only mode for large files to preserve mobile data
• Clean up completed downloads to manage storage

Development Status

This plugin is inspired by react-native-background-downloader and is currently being developed. Features may change as development progresses.

Documentation

Check the complete documentation for detailed implementation guides when the plugin reaches production readiness.