react-native-nitro-file-system

v0.4.0

Published

2 months ago

High-performance Node.js-compatible file system (fs) for React Native, powered by Nitro (JSI/C++) for zero-copy binary data handling and near-native speeds.

0High
0Medium
0Low

iwater

react-native ios android fs file-system node-fs nitro

react-native-nitro-file-system

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

中文文档

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.
🌐 URL Path Support: Handle file://, bookmark:// (iOS), and content:// (Android) URIs.
🔓 Native Picker: Built-in cross-platform file and directory picker with persistent access support.

Comparison with other Libraries

Installation

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

Standard Paths

The library provides a Paths object containing common system directory paths for cross-platform use.

import { Paths } from 'react-native-nitro-file-system';

console.log(Paths.cache);           // App caches directory
console.log(Paths.document);        // App documents directory
console.log(Paths.temp);            // Temporary directory
console.log(Paths.library);         // (iOS only) Library directory
console.log(Paths.mainBundle);      // (iOS only) Main bundle directory
console.log(Paths.externalCache);   // (Android only) External caches
console.log(Paths.externalStorage); // (Android only) External storage root

Basic Usage

Read and Write Files

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');

### Recursive Copying (cp / cpSync)

The library supports high-performance recursive directory copying, matching the behavior of Node.js `fs.cp`.

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

// Sync recursive copy
fs.cpSync('/path/to/src', '/path/to/dest', { recursive: true, force: true });

// Async recursive copy
await fs.promises.cp('/path/to/src', '/path/to/dest', { recursive: true });

#### `CpOptions`

| Option | Type | Default | Description | Supported |
| :--- | :--- | :--- | :--- | :--- |
| `recursive` | `boolean` | `false` | Copy directories recursively. | ✅ |
| `force` | `boolean` | `true` | Overwrite existing files. | ✅ |
| `dereference`| `boolean` | `false` | Dereference symlinks. | ✅ |
| `errorOnExist`| `boolean` | `false` | Throw error if destination exists and `force` is false. | ✅ |
| `preserveTimestamps` | `boolean` | `false` | Preserve mtime and atime from source. | ✅ |
| `filter` | `Function`| `undefined` | Filter function for files/directories. | ❌ |
| `mode` | `number` | `0` | Modifiers for copy operation. | ❌ |


### URL-style Path Support

The library provides robust support for URL-style paths and standard `URL` objects across all API methods. This is particularly useful when working with Expo or React Native components that return `file://` URIs.

- **Automatic Decoding**: Percent-encoded characters (like `%20` for spaces) are automatically decoded.
- **Protocol Handling**: Both `file://` and `file:/` prefixes are supported.
- **URL Objects**: You can pass standard JavaScript `URL` objects directly to any `fs` method.

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

// 1. Using file:// URI strings with percent encoding
const uri = 'file:///path/to/my%20document.txt';
fs.writeFileSync(uri, 'Content with spaces');

// 2. Using standard URL objects
const url = new URL('file:///path/to/config.json');
const data = fs.readFileSync(url, 'utf8');

// 3. Works with all APIs including Streams and Promises
const promiseContent = await fs.promises.readFile(new URL('file:///path/abc.txt'));
const stream = fs.createReadStream('file:///path/to/large_file.bin');

Android Content URIs

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.

// 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);

Android Asset (asset://) Support

The library provides direct, high-performance access to Android's assets directory via the asset:// protocol.

Read-Only: Since APK assets are packaged as read-only, only read-related operations are supported.
Path format: Use asset:// followed by the relative path within your project's src/main/assets directory.
Directory Support: You can list files in an asset directory using fs.readdir or recursively copy an entire asset directory using fs.cp.
copyFile Support: You can use asset:// as the source path in fs.cp and fs.copyFile to extract assets to other directories.

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

// Recursive copy a bundled asset directory to documents
fs.cpSync('asset://web-bundle/ruffle', `${Paths.document}/ruffle`, { recursive: true });

// Copy an asset file to the documents directory
fs.copyFileSync('asset://data/db.sqlite', `${Paths.document}/app.db`);

// Read a bundled configuration file
const config = fs.readFileSync('asset://config/settings.json', 'utf8');

// List files in an asset directory
const files = fs.readdirSync('asset://web-content');

// Check if an asset exists
if (fs.existsSync('asset://models/default.bin')) {
  const stats = fs.statSync('asset://models/default.bin');
  console.log(`Asset size: ${stats.size}`);
}

Note: asset:// is supported on both Android and iOS.

On Android, it accesses binary data directly from the APK via AssetManager.
On iOS, it maps to the Main Bundle directory.

iOS Bookmark URI Support

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.

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"

Native File Picker

Nitro File System includes a high-performance native file and directory picker that integrates seamlessly with the library's path system.

import fs, { pickFiles, pickDirectory } from 'react-native-nitro-file-system';

// 1. Pick and Import multiple images (copies to app cache)
const importedFiles = await pickFiles({
  multiple: true,
  mode: 'import',
  extensions: ['.jpg', '.png']
});

for (const file of importedFiles) {
  console.log(`Imported to cache: ${file.path}`);
  // No need for long-term access request for imported files
}

// 2. Pick and Open files in-place (persistent access)
const openedFiles = await pickFiles({
  multiple: true,
  mode: 'open',
  requestLongTermAccess: true 
});

for (const file of openedFiles) {
  console.log(`Resource path: ${file.path}`);
  if (file.bookmark) {
    console.log(`Persistent bookmark: ${file.bookmark}`);
  }
}

// 3. Pick a directory
const picked = await pickDirectory({
  requestLongTermAccess: true
});
console.log(`Selected directory: ${picked.path}`);
if (picked.bookmark) {
  console.log(`Persistent bookmark: ${picked.bookmark}`);
}

// List files in the picked directory (works with path or bookmark)
const entries = await fs.promises.readdir(picked.bookmark ?? picked.path);
console.log(entries);

File Pick Options

Directory Pick Options

Picked Result

pickFiles returns Promise<PickedFile[]>
pickDirectory returns Promise<PickedDirectory>

Platform Specifics

Android: Returns content:// URIs in both path and bookmark. If requestLongTermAccess is enabled, the library automatically calls takePersistableUriPermission for you.
iOS: Returns standard file paths in path. If requestLongTermAccess is enabled, it returns bookmark:// URIs in bookmark which provide security-scoped access. These URIs are natively supported by all other fs methods in this library.

Native Picker & Persistent Access

On iOS and Android, accessing files outside of the application's sandbox (like external storage or specific folders) requires explicit user permission. The library provides a native picker and a way to maintain persistent access through security-scoped bookmarks (iOS) or persistable URI permissions (Android).

Picking Files and Directories

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

// Pick files (returns PickedFile[])
const files = await fs.pickFiles({
  multiple: true,
  extensions: ['.txt', '.pdf'],
  requestLongTermAccess: true    // Recommended for persistent access
});

// Pick a directory (returns PickedDirectory)
const picked = await fs.pickDirectory({
  requestLongTermAccess: true
});
console.log(picked.path);     // Physical path
console.log(picked.bookmark); // bookmark://... on iOS, content://... on Android

// You can use the returned bookmark directly with any fs method
const items = fs.readdirSync(picked.bookmark ?? picked.path);

iOS Security Scoped Bookmarks

When requestLongTermAccess: true is passed to pickFiles or when using pickDirectory, the library returns a special bookmark:// URI on iOS. This URI embeds a security-scoped bookmark.

Seamless Access: The library automatically manages security-scoped resource access for every fs call using a bookmark:// URI.
Path Joining: You can join paths with a bookmark URI (e.g., using ${uri}/file.txt), and the library will correctly resolve the path while maintaining security scoping.
Long-term Storage: These URIs can be saved (e.g., in MMKV) and reused across app restarts.
Manual Bookmarks: Use fs.getBookmark(path) to generate a bookmark for an existing file or directory.

Android Persistable URIs

On Android, pickFiles and pickDirectory return content:// URIs. The library automatically requests persistable URI permissions when possible, ensuring the app maintains access after reboot.

Compatibility: The Node.js-compatible API handles content:// URIs for reading, writing, and directory listing.
SAF Tree Support: readdir and stat are supported for directory tree URIs returned by pickDirectory.

License

ISC

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

react-native-nitro-file-system

Features

Comparison with other Libraries

Installation

API Compatibility

Standard Paths

Basic Usage

Read and Write Files

Android Content URIs

Android Asset (asset://) Support

iOS Bookmark URI Support

Native File Picker

File Pick Options

Directory Pick Options

Picked Result

Platform Specifics

Native Picker & Persistent Access

Picking Files and Directories

iOS Security Scoped Bookmarks

Android Persistable URIs

License