React Native File System (react-native-fs)

Common errors

• Invariant Violation: `new NativeEventEmitter()` was called with a non-null argument without the native module implementing `addListener` and `removeListeners`.

  cause Using `react-native-fs` with a React Native version that expects `NativeEventEmitter` compliance, but the installed `react-native-fs` version is too old.
  fix Upgrade `react-native-fs` to version `2.19.0` or newer: `npm install react-native-fs@latest` or `yarn add react-native-fs@latest`.

• Undefined symbol: _OBJC_CLASS_$_RCTImageLoader

  cause iOS build failure due to changes in React Native's internal `RCTImageLoader` import paths (specifically for RN > 0.60).
  fix Upgrade `react-native-fs` to version `2.15.1` or higher, which includes a fix for this issue by importing `RCTImageLoaderProtocol`.

• TypeError: Cannot read property 'DocumentDirectoryPath' of undefined

  cause The `RNFS` native module was not correctly linked or initialized, or the JavaScript import is incorrect.
  fix Ensure the library is properly linked (using `react-native link react-native-fs` or manual linking as per documentation). Verify the import statement is `import RNFS from 'react-native-fs';`.

• Task 'assembleRelease' failed. Android resource linking failed.

  cause Common Android build issue, often related to AndroidX migration status or incorrect Gradle configuration.
  fix Verify that your `react-native-fs` version supports your AndroidX migration status (v2.14.0+ for AndroidX). Check your `android/app/build.gradle` and `android/settings.gradle` for correct `react-native-fs` package inclusion, especially if using manual linking.

Warnings

• breaking Breaking changes in compatibility with React Native versions require specific `react-native-fs` versions. Failure to install the correct version will lead to build errors or runtime crashes.
  Fix: For RN < 0.57, install `@2.11.17`. For RN >= 0.57 and Gradle >= 3, install `>= @2.13.2`. For RN >= 0.61, install `>= @2.16.0`.
• breaking `react-native-fs` versions prior to `2.14.0` do not support AndroidX. Projects migrating to AndroidX must upgrade.
  Fix: Upgrade to `react-native-fs` version `2.14.0` or higher to gain AndroidX support. Ensure your Android project is fully migrated to AndroidX.
• breaking The `size` property returned by file `stat` operations changed from `Int` to `Double` for increased precision, particularly affecting larger files.
  Fix: Update any code that relies on the `size` property to expect a `Double` instead of an `Int`.
• gotcha On Android, the `DocumentDirectory` is strictly mapped to the application's private `files` directory. This differs from iOS, where it might have broader permissions or map to different system directories. Access to external storage requires additional permissions and may not be directly supported through this path.
  Fix: Be aware of Android's scoped storage and file access limitations. For external storage, consider using methods like `ExternalStorageDirectoryPath` or `DownloadDirectoryPath` and ensure appropriate permissions (`READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE`) are declared and requested at runtime.
• gotcha iOS background downloads require specific setup and careful handling of sessions. Improper configuration can lead to downloads failing or not resuming correctly.
  Fix: Follow the 'Background Downloads Tutorial (iOS)' in the official documentation carefully. Ensure `Manually flush & invalidate session upon completion` (as fixed in v2.17.0) is considered when managing download tasks.
• gotcha Older versions of `react-native-fs` (< 2.19.0) did not properly implement `addListener` and `removeListeners` methods, leading to `NativeEventEmitter` warnings in newer React Native environments.
  Fix: Upgrade to `react-native-fs` version `2.19.0` or higher to resolve `NativeEventEmitter` warnings.

Install

• npm install react-native-fs npm
• yarn add react-native-fs yarn
• pnpm add react-native-fs pnpm

Imports

• RNFS
  wrong:

  import { RNFS } from 'react-native-fs';

  correct:

  import RNFS from 'react-native-fs';

  The library primarily uses a default export pattern where `RNFS` is the main object containing all methods and constants.
• DocumentDirectoryPath
  wrong:

  import { DocumentDirectoryPath } from 'react-native-fs';

  correct:

  import RNFS from 'react-native-fs';
  const path = RNFS.DocumentDirectoryPath;

  Constants like directory paths are properties of the default `RNFS` export.
• RNFS (CommonJS)

  const RNFS = require('react-native-fs');

  For older React Native projects or environments that still rely on CommonJS modules. Modern projects should prefer ESM imports.

Quickstart

This example demonstrates basic file operations: writing a string to a temporary file, reading its content, checking its existence, retrieving its statistics, and finally deleting it. It uses `RNFS.TemporaryDirectoryPath` for cross-platform compatibility.

import RNFS from 'react-native-fs';

const fileName = 'test.txt';
const content = 'Hello from react-native-fs!';
const filePath = `${RNFS.TemporaryDirectoryPath}/${fileName}`;

async function runFsExample() {
  try {
    // 1. Write a file
    await RNFS.writeFile(filePath, content, 'utf8');
    console.log(`File written to: ${filePath}`);

    // 2. Read the file
    const readContent = await RNFS.readFile(filePath, 'utf8');
    console.log(`File content: ${readContent}`);

    if (readContent !== content) {
      throw new Error('Content mismatch!');
    }

    // 3. Check if file exists
    const exists = await RNFS.exists(filePath);
    console.log(`File exists: ${exists}`);

    // 4. Get file stats
    const statResult = await RNFS.stat(filePath);
    console.log(`File size: ${statResult.size} bytes`);

    // 5. Delete the file
    await RNFS.unlink(filePath);
    console.log(`File deleted: ${filePath}`);

    const deletedExists = await RNFS.exists(filePath);
    console.log(`File exists after deletion: ${deletedExists}`);

  } catch (error) {
    console.error('An error occurred during FS operations:', error);
  }
}

runFsExample();