react-native-nitro-file-system

A high-performance, Node.js-compatible file system (fs) module for React Native, powered by Nitro Modules.

![platform]()
![compatibility]()
中文文档

Features

- 🚀 Extreme Performance: Low-overhead communication via JSI and Nitro.
- 📦 Zero-copy Binary Data: Efficiently handle large files using ArrayBuffer and NitroBuffer.
- 🛠️ Node.js Compatible API: Supports fs methods like readFile, writeFile, mkdir, stat, and more (Sync & Async).
- 🏗️ Streaming Support: Built-in ReadStream and WriteStream for efficient data processing.
- 📂 Directory & Watcher: Support for directory iteration and file system watching.

Comparison with other Libraries

| Feature | react-native-fs | expo-file-system | react-native-blob-util | Nitro File System |
| :--- | :--- | :--- | :--- | :--- |
| Architecture | Legacy Bridge | Turbo Modules / Expo | Legacy Bridge / C++ | Nitro (JSI / C++) |
| Communication | High (Base64/JSON) | Medium | Medium | Ultra Low (Direct JSI) |
| Binary Handling | Slow (Base64) | Fast | Fast | Top (Zero-copy Buffers) |
| API Style | Custom | Custom | Stream / Mixed | Node.js fs Compatible |
| Sync API | Poor | None | Limited | Full Support |

Installation

``sh
npm install react-native-nitro-file-system react-native-nitro-modules react-native-nitro-buffer


or


yarn add react-native-nitro-file-system react-native-nitro-modules react-native-nitro-buffer
`

API Compatibility

| Category | Status | Supported Methods |
| :--- | :--- | :--- |
| File I/O | ✅ 100% | open, read, write, close, readFile, writeFile, appendFile, truncate, fsync, readv, writev |
| Metadata | ✅ 100% | stat, lstat, fstat, access, utimes, futimes, lutimes (including bigint support) |
| Directories | ✅ 100% | mkdir, rmdir, readdir, rm, mkdtemp, opendir (Dir class) |
| Permissions | ✅ 100% | chmod, fchmod, lchmod, chown, fchown, lchown |
| Links | ✅ 100% | link, symlink, readlink, realpath |
| Watching | ✅ 100% | watch, watchFile, unwatchFile |
| Streams | ✅ 100% | createReadStream, createWriteStream |
| Promises | ✅ 100% | fs.promises.* (Full coverage) |

Basic Usage

$3

`typescript
import fs from 'react-native-nitro-file-system';

// Write a file (Sync)
fs.writeFileSync('/path/to/file.txt', 'Hello Nitro!');

// Read a file (Async)
fs.readFile('/path/to/file.txt', 'utf8', (err, data) => {
if (err) throw err;
console.log(data); // "Hello Nitro!"
});

// Using Promises
const content = await fs.promises.readFile('/path/to/file.txt', 'utf8');
`




$3

The library supports Android content:// URIs for the following operations:
- Read/Write: fs.open, fs.read, fs.write, fs.readFile, fs.writeFile.
- Metadata: fs.stat, fs.lstat, fs.access (existence check).
- Cleanup: fs.unlink, fs.rm.
- Utility: fs.copyFile.

Note: Directory operations (mkdir, readdir, rename, chmod) are not supported for content:// URIs as they are virtual resources.

`typescript
// Read directly from a content:// URI
const contentUri = 'content://com.android.providers.media.documents/document/image%3A1234';
const data = fs.readFileSync(contentUri, 'base64');

// Get file stats
const stats = fs.statSync(contentUri);
console.log(stats.size);
`

$3

Includes first-class support for iOS bookmark:// URIs, allowing persistent access to security-scoped resources (like iCloud Drive files picked via Document Picker) without copying them.

`typescript
import fs, { getBookmark, resolveBookmark } from 'react-native-nitro-file-system';

// 1. Convert specific path to bookmark
const bookmark = getBookmark('/path/to/file');

// 2. Access using bookmark URI
const stat = await fs.promises.stat(bookmark);
const content = await fs.promises.readFile(bookmark);

// 3. Resolve bookmark back to physical path
const path = resolveBookmark(bookmark);
console.log(path); // "/path/to/file"
``

License

ISC