rn-file-toolkit

v1.0.8

Published

4 hours ago

The ultimate native file management toolkit for React Native. Features background downloads, resumable uploads, filesystem operations, queues, zip/unzip, and media utilities with zero third-party dependencies.

rn-file-toolkit is the modern replacement for legacy file libraries. Download, upload, manage queues, extract archives, and interact with the filesystem—all powered by pure native implementations (Kotlin + Swift) with zero third-party dependencies.

⭐ Star this repo if you find it useful to help others discover it!

📖 Table of Contents

🚀 Why rn-file-toolkit?

Most React Native file solutions (rn-fetch-blob, react-native-fs) are fragmented, lightly maintained, or lack modern features. rn-file-toolkit gives you a unified, TurboModule-compatible API utilizing OS-native managers (URLSession on iOS, DownloadManager on Android) for reliable, battery-efficient operations.

✨ Highlights

🪝 Drop-in React Hooks: Built-in state management (useDownload) for progress and controls.
📥 Background Ready: Downloads and uploads survive app suspension with automatic re-attachment.
🚦 Smart Queueing: Cap concurrency and set priorities without touching native code.
🛡️ Resilient: Auto-retries on network errors with exponential backoff and HTTP resume.
🗜️ Zero-Dependency Zip: Uses native java.util.zip and iOS zlib.
🗄️ Rich File System API: Comprehensive FS methods (readFile, writeFile, copyFile, mkdir, stat, etc.).
🛠️ Expo Compatible: Seamless integration with Expo custom dev clients.

🥊 How does it compare?

If you've been working with React Native for a while, you've probably used rn-fetch-blob or react-native-fs. While they were fantastic tools back in the day, they haven't aged well and often struggle with modern requirements like seamless Expo integration or background persistence. You might have also tried expo-file-system, which is great for the basics but starts to fall short when you need smart queueing or multipart uploads.

We built rn-file-toolkit because we were tired of stitching together multiple unmaintained libraries just to download a file reliably in the background while keeping the UI updated.

Here's how it stacks up against the crowd:

We hook directly into OS-level managers (URLSession on iOS, DownloadManager on Android) to provide maximum reliability, battery efficiency, and zero headaches.

🌐 Documentation Website

Full docs are hosted on GitHub Pages:

https://chavan-labs.github.io/rn-file-toolkit/

📦 Installation

# npm
npm install rn-file-toolkit

# yarn
yarn add rn-file-toolkit

# pnpm
pnpm add rn-file-toolkit

(Optional) If you are not using Expo or an auto-linking setup, run pod install in your ios directory.

⚡ Quick Start: `useDownload`

The easiest way to manage a download inside a React component. Get status, rich progress (with speed & ETA), and full controls instantly.

import React from 'react';
import { View, Text, Button } from 'react-native';
import { useDownload } from 'rn-file-toolkit';

export default function DownloadScreen() {
  const { start, pause, resume, cancel, status, progress, result } =
    useDownload();

  return (
    <View style={{ padding: 20 }}>
      <Button
        title="Start Download"
        onPress={() =>
          start({
            url: 'https://example.com/large-video.mp4',
            destination: 'documents',
          })
        }
      />

      {status === 'downloading' && progress && (
        <View style={{ marginTop: 20 }}>
          <Text>Progress: {progress.percent.toFixed(1)}%</Text>
          <Text>
            Speed: {(progress.speedBps / 1024 / 1024).toFixed(2)} MB/s
          </Text>
          <Text>ETA: {progress.etaSeconds.toFixed(0)} seconds</Text>
          <View style={{ flexDirection: 'row', gap: 10, marginTop: 10 }}>
            <Button title="Pause" onPress={pause} />
            <Button title="Cancel" onPress={cancel} color="red" />
          </View>
        </View>
      )}

      {status === 'paused' && <Button title="Resume" onPress={resume} />}
      {status === 'done' && (
        <Text style={{ color: 'green' }}>✅ Saved: {result?.filePath}</Text>
      )}
      {status === 'error' && (
        <Text style={{ color: 'red' }}>❌ Error: {result?.error}</Text>
      )}
    </View>
  );
}

🛠️ Core APIs

Background Downloads

For programmatic, queue-aware background downloads outside of React components.

import { download } from 'rn-file-toolkit';

const result = await download({
  url: 'https://example.com/file.pdf',
  fileName: 'report.pdf', // Optional custom filename
  destination: 'documents', // 'downloads' | 'cache' | 'documents'
  background: true, // Survive app suspension
  headers: { Authorization: 'Bearer token' },
  queue: true, // Join the managed queue
  priority: 'high', // 'high' | 'normal'
  downloadId: 'my-unique-id', // Optional custom ID for tracking
  notificationTitle: 'Downloading report…', // Android notification
  notificationDescription: 'Please wait',
  checksum: { hash: 'abc123...', algorithm: 'sha256' }, // Verify integrity
  retry: {
    attempts: 3,
    delay: 1000,
    onRetry: (attempt, error) => console.warn(`Retry #${attempt}: ${error}`),
  },
  onProgress: (p) => console.log(`${p.percent.toFixed(1)}% downloaded`),
});

console.log(result.filePath); // Path to the downloaded file

Download Controls

Pause, resume, or cancel any active download by its ID—works both inside and outside React components.

import {
  download,
  pauseDownload,
  resumeDownload,
  cancelDownload,
} from 'rn-file-toolkit';

// Start a download with a known ID
const result = download({
  url: 'https://example.com/large-video.mp4',
  downloadId: 'video-1',
  destination: 'documents',
});

// Later… pause, resume, or cancel by ID
await pauseDownload('video-1');
await resumeDownload('video-1');
await cancelDownload('video-1');

Multipart Uploads

Robust, memory-efficient multipart file uploading for large media or documents.

import { upload } from 'rn-file-toolkit';

const result = await upload({
  url: 'https://api.example.com/v1/upload',
  filePath: '/path/to/local/image.jpg',
  fieldName: 'file',
  headers: { Authorization: 'Bearer token' },
  parameters: { userId: '123', folder: 'avatars' },
  uploadId: 'upload-1', // Optional custom ID for tracking
  onProgress: (percent) => console.log(`Uploading: ${percent}%`),
});

console.log(result.status); // HTTP status code
console.log(result.data); // Server response body

Queue Management

Control download concurrency globally and inspect the queue state.

import { setQueueOptions, getQueueStatus } from 'rn-file-toolkit';

// Set the maximum number of simultaneous downloads
setQueueOptions({ maxConcurrent: 3 });

// Inspect the queue at any time
const status = getQueueStatus();
console.log(status.active); // Currently downloading
console.log(status.pending); // Waiting in queue
console.log(status.maxConcurrent); // Concurrency cap

You can also retrieve all downloads currently running in the background (useful after app re-launch):

import { getBackgroundDownloads } from 'rn-file-toolkit';

const active = await getBackgroundDownloads();
console.log(active); // Array of background download descriptors

File System (FS)

Perform native filesystem operations securely. All methods are available both as the namespaced fs object and as standalone named exports.

import { fs } from 'rn-file-toolkit';

// Check & Inspect
const exists = await fs.exists('/path/to/data.json');
const stats = await fs.stat('/path/to/data.json'); // { path, name, size, modified, isDir }

// Read & Write
await fs.writeFile('/path/to/data.txt', 'Hello World', 'utf8'); // Also supports 'base64'
const content = await fs.readFile('/path/to/data.txt', 'utf8');

// Manage Folders & Files
await fs.mkdir('/path/to/new_folder');
const files = await fs.ls('/path/to/new_folder');
await fs.copyFile('/path/src.txt', '/path/dest.txt');
await fs.moveFile('/path/old.txt', '/path/new.txt');
await fs.deleteFile('/path/unwanted.txt');

Tip: You can also import each FS method individually:
import { exists, stat, readFile, writeFile, copyFile, moveFile, deleteFile, mkdir, ls } from 'rn-file-toolkit';

Zip & Unzip Archives

Compress and extract archives directly on the device using native java.util.zip (Android) and zlib (iOS).

import { unzip, zip } from 'rn-file-toolkit';

// Extract a downloaded zip
const unzipResult = await unzip('/path/to/bundle.zip', '/path/to/extract-folder');
console.log(unzipResult.files); // List of extracted file paths

// Compress user data before uploading
const zipResult = await zip('/path/to/user-data-folder', '/path/to/backup.zip');
console.log(zipResult.zipPath); // Path to the created archive

Cache Management

Inspect and clear files stored in the cache directory.

import { getCachedFiles, clearCache } from 'rn-file-toolkit';

// List all cached files with metadata
const cache = await getCachedFiles();
cache.files?.forEach((f) => {
  console.log(f.fileName, f.filePath, f.size, f.modifiedAt);
});

// Wipe the entire cache directory
await clearCache();

Media & Utilities

Helpful tools for sharing, opening, and encoding files.

import {
  saveBase64AsFile,
  urlToBase64,
  shareFile,
  openFile,
} from 'rn-file-toolkit';

// Base64 to File (accepts raw base64 or data URIs)
await saveBase64AsFile({
  base64Data: 'data:image/png;base64,...',
  destination: 'documents',
  fileName: 'image.png',
});

// URL to Base64 (great for caching small images)
const b64 = await urlToBase64({
  url: 'https://example.com/icon.png',
  headers: { Authorization: 'Bearer token' }, // Optional
});
console.log(b64.mimeType); // e.g. 'image/png'
console.log(b64.dataUri); // Ready-to-use data URI string

// Native Share Sheet
await shareFile({
  filePath: '/path/to/report.pdf',
  title: 'Share report', // Optional
  subject: 'Monthly report', // Optional (email subject)
});

// Open with default system app
await openFile({
  filePath: '/path/to/report.pdf',
  mimeType: 'application/pdf',
});

Event Listeners

Subscribe to global download and upload lifecycle events. Each listener returns an unsubscribe function.

import {
  onDownloadComplete,
  onDownloadError,
  onDownloadRetry,
  onUploadProgress,
} from 'rn-file-toolkit';

// Fires when any download finishes successfully
const unsub1 = onDownloadComplete((event) => {
  console.log('Download done:', event);
});

// Fires when any download fails
const unsub2 = onDownloadError((event) => {
  console.error('Download failed:', event);
});

// Fires on each retry attempt (when retry is configured)
const unsub3 = onDownloadRetry((event) => {
  console.warn(`Retry #${event.attempt}:`, event.error);
});

// Fires on upload progress updates
const unsub4 = onUploadProgress((event) => {
  console.log(`Upload ${event.uploadId}: ${event.progress}%`);
});

// Clean up when done
unsub1();
unsub2();
unsub3();
unsub4();

📚 API Reference

Types & Interfaces

Exported Functions

🎪 Expo Support

rn-file-toolkit works seamlessly with Expo custom development clients (EAS Build / npx expo run:android / npx expo run:ios). Since it contains native code, it is not compatible with Expo Go.

An Expo config plugin is included automatically. No extra configuration is needed in your app.json unless you want to customize permissions.

🤝 Contributing

Contributions are welcome! If you find a bug or want to request a feature, please open an issue.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request