rn-file-toolkit

v1.0.14

Published

a month 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.

Downloads

147

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 + Objective-C++) 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, appendFile, copyFile, mkdir, stat, hash, df, etc.).
🍪 Cookie Management: Read and clear HTTP cookies from the platform's shared cookie store.
📸 MediaStore / Photos Library: Save files directly to the device's shared media store.
📦 Session Management: Group files into named sessions for batch cleanup.
🛠️ 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/

⬆️ Migrating from rn-downloader

rn-downloader has been officially rebranded to rn-file-toolkit. The new package is a drop-in replacement for all existing download functionality and adds a full suite of new capabilities: a rich Filesystem API, native Zip/Unzip, managed queues, multipart uploads, base64 utilities, native sharing, and more.

Migration takes less than 5 minutes. Follow the steps below.

Step 1 — Uninstall the old package

# npm
npm uninstall rn-downloader

# yarn
yarn remove rn-downloader

# pnpm
pnpm remove rn-downloader

Step 2 — Install the new package

# 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.

Step 3 — Update your imports

Replace every occurrence of rn-downloader with rn-file-toolkit across your codebase. All previously exported names are preserved.

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

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

- import { useDownload } from 'rn-downloader';
+ import { useDownload } from 'rn-file-toolkit';

That's it — no other code changes are required. Every API signature from rn-downloader is 100% compatible.

API Compatibility Table

All rn-downloader exports map directly to rn-file-toolkit:

What's new after migration?

Once you've migrated, you get access to everything new in rn-file-toolkit at no extra cost:

| Feature | Description | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | | 📂 Full Filesystem API | readFile, writeFile, copyFile, moveFile, deleteFile, mkdir, ls, stat, exists — all native, no dependencies. | | 📦 Native Zip & Unzip | Compress and extract archives using java.util.zip (Android) and zlib (iOS) — zero third-party libs. | | 📤 Multipart Uploads | Memory-efficient upload() with progress tracking and a custom uploadId. | | 🔗 Base64 & Data URI | urlToBase64() and saveBase64AsFile() for encoding/decoding without extra packages. | | 📤 Native Sharing & Opening | shareFile() triggers the OS share sheet; openFile() opens any file in its default app. | | 🍪 Cookie Management | Read and clear HTTP cookies from the platform's shared cookie store. | | 📸 MediaStore / Photos Library | Save files directly to the device gallery or Downloads folder. | | 💾 Disk Space | df() returns free and total bytes for the device storage. | | 🗂️ Session Management | Group files into named sessions for easy batch cleanup. |

Need help?

If you run into any issues during migration, please open an issue on the new GitHub repository.

📦 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();

Disk Space

Check available and total device storage.

import { df } from 'rn-file-toolkit';
// or: import { fs } from 'rn-file-toolkit'; const result = await fs.df();

const space = await df();
if (space.success) {
  console.log(`Free: ${(space.freeBytes! / 1024 / 1024 / 1024).toFixed(2)} GB`);
  console.log(
    `Total: ${(space.totalBytes! / 1024 / 1024 / 1024).toFixed(2)} GB`
  );
}

File Appending

Append data to the end of a file without overwriting existing content.

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

// Append a log line
await appendFile('/path/to/log.txt', 'New log entry\n');

// Append base64 data
await appendFile('/path/to/data.bin', base64String, 'base64');

File Hashing

Compute the MD5, SHA-1, or SHA-256 hash of any file on disk.

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

const result = await hash('/path/to/file.zip', 'sha256');
if (result.success) {
  console.log('SHA-256:', result.hash);
}

Session Management

Group downloaded files into sessions for batch cleanup. Useful for temporary file workflows.

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

// Download files and track them in a session
const result = await download({
  url: 'https://example.com/tmp1.pdf',
  destination: 'cache',
});
if (result.filePath) session.add('my-workflow', result.filePath);

const result2 = await download({
  url: 'https://example.com/tmp2.pdf',
  destination: 'cache',
});
if (result2.filePath) session.add('my-workflow', result2.filePath);

// List session files
console.log(session.get('my-workflow')); // ['/path/to/tmp1.pdf', '/path/to/tmp2.pdf']

// Clean up everything when done
await session.clear('my-workflow');

Note: Session data lives in memory and does not persist across app restarts.

Cookie Management

Read and clear HTTP cookies from the platform's shared cookie store.

import { getCookies, clearCookies } from 'rn-file-toolkit';
// or: import { cookies } from 'rn-file-toolkit';

// Get cookies for a domain
const result = await getCookies('example.com');
result.cookies?.forEach((c) => {
  console.log(`${c.name}=${c.value} (domain: ${c.domain})`);
});

// Clear cookies for a specific domain
await clearCookies('example.com');

// Clear ALL cookies
await clearCookies();

MediaStore / Photos Library

Save files to the device's shared media store (Android MediaStore / iOS Photos Library).

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

// Save an image to the Photos library / gallery
const result = await saveToMediaStore({
  filePath: '/path/to/photo.jpg',
  mediaType: 'image',
  album: 'MyApp', // Optional album/subfolder
});
console.log(result.uri); // content://... (Android) or file path (iOS)

// Save a video
await saveToMediaStore({
  filePath: '/path/to/video.mp4',
  mediaType: 'video',
});

// Save to the Downloads folder
await saveToMediaStore({
  filePath: '/path/to/report.pdf',
  mediaType: 'download',
});

Permissions: iOS requires NSPhotoLibraryAddUsageDescription in your Info.plist for image/video saves. Android may require WRITE_EXTERNAL_STORAGE on API < 29.

📚 API Reference

Types & Interfaces

Exported Functions

| Function | :----------------------- | download | upload | pauseDownload | resumeDownload | cancelDownload | setQueueOptions | getQueueStatus | getBackgroundDownloads | getCachedFiles | clearCache | deleteFile | exists | stat | readFile | writeFile | copyFile | moveFile | mkdir | ls | unzip | zip | saveBase64AsFile | urlToBase64 | shareFile | openFile | onDownloadComplete | onDownloadError | onDownloadRetry | onUploadProgress | useDownload | df | appendFile | hash | getCookies | clearCookies | saveToMediaStore | fs | cookies | session | isAvailable | Signature | Description | | :--------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | | (options: DownloadOptions) => Promise<DownloadResult> | Download a file (supports queue, background, retries). | | (options: UploadOptions) => Promise<UploadResult> | Multipart upload a file. | | (id: string) => Promise<ActionResult> | Pause an active download by ID. | | (id: string) => Promise<ActionResult> | Resume a paused download by ID. | | (id: string) => Promise<ActionResult> | Cancel a download by ID. | | (options: QueueOptions) => void | Set global queue concurrency. | | () => QueueStatus | Get current queue state (active/pending counts). | | () => Promise<any> | Retrieve active background download descriptors. | | () => Promise<CacheResult> | List all files in the cache directory. | | () => Promise<ActionResult> | Delete all cached files. | | (path: string) => Promise<ActionResult> | Delete a single file by path. | | (path: string) => Promise<boolean> | Check if a file or directory exists. | | (path: string) => Promise<FsStat> | Get metadata for a file or directory. | | (path: string, encoding?: FsEncoding) => Promise<string> | Read file contents as a string. | | (path: string, data: string, encoding?: FsEncoding) => Promise<void> | Write a string to a file. | | (from: string, to: string) => Promise<void> | Copy a file. | | (from: string, to: string) => Promise<void> | Move or rename a file. | | (path: string) => Promise<void> | Create a directory (recursive). | | (path: string) => Promise<string[]> | List directory contents. | | (src: string, dest: string) => Promise<UnzipResult> | Extract a zip archive. | | (src: string, dest: string) => Promise<ZipResult> | Compress a folder into a zip archive. | | (options: SaveBase64Options) => Promise<SaveBase64Result> | Save a base64 string as a file. | | (options: UrlToBase64Options) => Promise<UrlToBase64Result> | Fetch a URL and return its content as base64. | | (options: ShareFileOptions) => Promise<ShareFileResult> | Open the native share sheet for a file. | | (options: OpenFileOptions) => Promise<OpenFileResult> | Open a file with the system default app. | | (cb) => () => void | Subscribe to download completion events. | | (cb) => () => void | Subscribe to download error events. | | (cb) => () => void | Subscribe to download retry events. | | (cb) => () => void | Subscribe to upload progress events. | | () => UseDownloadReturn | React hook for managing a download with state. | | () => Promise<DiskSpaceResult> | Get free and total device disk space. | | (path: string, data: string, encoding?: FsEncoding) => Promise<void> | Append data to a file. | | (path: string, algorithm?: HashAlgorithm) => Promise<HashResult> | Compute a file's hash digest. | | (domain: string) => Promise<CookiesResult> | Get cookies for a domain. | | (domain?: string) => Promise<ActionResult> | Clear cookies (domain or all). | | (options: MediaStoreOptions) => Promise<MediaStoreResult> | Save file to shared media store. | | FsApi | Namespaced object grouping all filesystem methods (includes df, appendFile, hash). | | { get, clear, clearAll } | Namespaced cookie management. | | SessionApi | Namespaced session management. | | boolean | true when the native module is linked — useful on web, in SSR and in tests. |

New Types & Interfaces

⚠️ Platform Notes

Behaviour that differs between iOS and Android, so you can plan for it up front. Each item is expanded in the troubleshooting guide.

| Topic | Note | | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | Cleartext HTTP | Android blocks http:// by default from API 28. Use https://, or opt in via usesCleartextTraffic. | | Pause / resume | Foreground downloads only. Android's system DownloadManager has no pause API, so pauseDownload() returns success: false for background: true. | | Background completion (iOS) | Forward handleEventsForBackgroundURLSession from your AppDelegate so the app is woken when a transfer finishes while suspended. | | getBackgroundDownloads() | status is the raw platform value and differs per platform. Use progress and the completion events for portable logic. | | readFile / urlToBase64 | Capped at 50 MB on both platforms to avoid exhausting memory across the bridge. | | saveToMediaStore | Android writes to the shared MediaStore. iOS saves images/videos to the Photo Library and copies other types into Documents (iOS has no shared media store). | | fs.* vs top-level | fs.* methods throw on failure; top-level helpers return { success: false, error } and never throw. | | Sessions | session.* is in-memory only and does not survive an app restart or a hot reload. |

🎪 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