react-native-nitro-unzip

High-performance ZIP operations for React Native, powered by Nitro Modules.

Read the full documentation

Features

• Fast — ~9,000+ files/sec on Android (post-NIO / java.util.zip.ZipFile migration in 0.5.0) and ~10,000+ files/sec on iOS (O_NOFOLLOW streaming writes), measured on nested 1000-entry archives on dev hardware
• Zero bridge overhead — progress callbacks via JSI, no serialization
• Cancellable — mid-write cancellation on Android (Thread.interrupt() + interruptible NIO channels), per-entry cancellation on iOS (Swift Concurrency)
• AES-256 password support — encrypted archives, zip & unzip, on both platforms
• Transactional extraction — zero partial state on mid-stream failure (rollback on both platforms)
• Concurrent operations — multiple tasks run independently
• Background execution — iOS background task management

Installation

npm install react-native-nitro-unzip react-native-nitro-modules
cd ios && pod install

Requires React Native 0.75+, Nitro Modules 0.35+, iOS 15.5+, Android minSdk 26+ (since 0.5.0), and Java 17 (Android).

Security defences (0.5.0+)

The 0.5.0 release added the same Zip Slip / symlink / case-collision / BiDi-spoofing defences to both Android and iOS:

• Path traversal (../escape), absolute paths, backslash separators
• NUL bytes, BiDi overrides/isolates (CVE-2021-42574 class), C0 control characters
• Length cap (1024 chars), empty entries, dot/dot-dot resolutions
• Case-insensitive + NFC-normalised duplicate detection (FAT32/HFS+/APFS-CI overwrite prevention)
• Symlink injection at the entry target OR in any ancestor directory
• Transactional extraction: any failure mid-extraction (corrupt entry, disk full, write error, cancellation) rolls back every file AND every intermediate directory we created before the error surfaces — the destination is either fully extracted or untouched

Errors carry a stable code (e.g. ENTRY_OUTSIDE_DESTINATION, SYMLINK_IN_ANCESTRY, WRONG_PASSWORD, CANCELLED) so JS handlers can branch programmatically rather than parsing localised messages.

iOS deployment target

The library depends on SSZipArchive, which requires iOS 15.5+. Ensure your app's Podfile (or Expo Podfile.properties.json) sets ios.deploymentTarget to 15.5 or higher.

Quick Example

import { getUnzip } from 'react-native-nitro-unzip';

const unzip = getUnzip();
const task = unzip.extract('/path/to/archive.zip', '/path/to/output');

task.onProgress((p) => {
  console.log(`${(p.progress * 100).toFixed(0)}% — ${p.extractedFiles}/${p.totalFiles} files`);
});

const result = await task.await();
console.log(`Extracted ${result.extractedFiles} files in ${result.duration}ms`);

Documentation

Visit the docs site for:

• Getting Started — installation and setup
• Extraction — extract archives with progress
• Compression — create ZIP archives
• Password Protection — encrypted archives
• Cancellation — cancel operations
• Performance — benchmarks and internals
• API Reference — auto-generated from TypeScript

Example

See the example app for a working demo.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT