{"id":11773,"library":"react-native-fs","title":"React Native File System (react-native-fs)","description":"react-native-fs provides comprehensive native filesystem access for React Native applications across iOS, Android, and Windows platforms. It offers a robust API for common file operations such as reading, writing, and deleting files, managing directories, and facilitating advanced use cases like background file downloads and uploads with progress tracking. The library is actively maintained, with the current stable version being 2.20.0, and receives regular updates to address compatibility with new React Native versions and underlying OS changes, exemplified by recent fixes for iOS crashes and Android type corrections. A key differentiator is its direct native integration, enabling features like handling content URIs on Android and asset video URIs on iOS, which are crucial for complex media and document management within mobile applications. It carefully manages compatibility across various React Native versions, requiring specific `react-native-fs` versions depending on the host `react-native` and Gradle versions, highlighting its sensitivity to the broader ecosystem.","status":"active","version":"2.20.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/itinance/react-native-fs","tags":["javascript","react-component","react-native","ios","android","fs","filesystem","download","upload","typescript"],"install":[{"cmd":"npm install react-native-fs","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-fs","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-fs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for all React Native applications using this library.","package":"react-native","optional":false},{"reason":"Peer dependency for React Native Windows support.","package":"react-native-windows","optional":true}],"imports":[{"note":"The library primarily uses a default export pattern where `RNFS` is the main object containing all methods and constants.","wrong":"import { RNFS } from 'react-native-fs';","symbol":"RNFS","correct":"import RNFS from 'react-native-fs';"},{"note":"Constants like directory paths are properties of the default `RNFS` export.","wrong":"import { DocumentDirectoryPath } from 'react-native-fs';","symbol":"DocumentDirectoryPath","correct":"import RNFS from 'react-native-fs';\nconst path = RNFS.DocumentDirectoryPath;"},{"note":"For older React Native projects or environments that still rely on CommonJS modules. Modern projects should prefer ESM imports.","symbol":"RNFS (CommonJS)","correct":"const RNFS = require('react-native-fs');"}],"quickstart":{"code":"import RNFS from 'react-native-fs';\n\nconst fileName = 'test.txt';\nconst content = 'Hello from react-native-fs!';\nconst filePath = `${RNFS.TemporaryDirectoryPath}/${fileName}`;\n\nasync function runFsExample() {\n  try {\n    // 1. Write a file\n    await RNFS.writeFile(filePath, content, 'utf8');\n    console.log(`File written to: ${filePath}`);\n\n    // 2. Read the file\n    const readContent = await RNFS.readFile(filePath, 'utf8');\n    console.log(`File content: ${readContent}`);\n\n    if (readContent !== content) {\n      throw new Error('Content mismatch!');\n    }\n\n    // 3. Check if file exists\n    const exists = await RNFS.exists(filePath);\n    console.log(`File exists: ${exists}`);\n\n    // 4. Get file stats\n    const statResult = await RNFS.stat(filePath);\n    console.log(`File size: ${statResult.size} bytes`);\n\n    // 5. Delete the file\n    await RNFS.unlink(filePath);\n    console.log(`File deleted: ${filePath}`);\n\n    const deletedExists = await RNFS.exists(filePath);\n    console.log(`File exists after deletion: ${deletedExists}`);\n\n  } catch (error) {\n    console.error('An error occurred during FS operations:', error);\n  }\n}\n\nrunFsExample();","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<=2.20.0"},{"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.","message":"`react-native-fs` versions prior to `2.14.0` do not support AndroidX. Projects migrating to AndroidX must upgrade.","severity":"breaking","affected_versions":"<2.14.0"},{"fix":"Update any code that relies on the `size` property to expect a `Double` instead of an `Int`.","message":"The `size` property returned by file `stat` operations changed from `Int` to `Double` for increased precision, particularly affecting larger files.","severity":"breaking","affected_versions":"<2.14.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.1.0"},{"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.","message":"iOS background downloads require specific setup and careful handling of sessions. Improper configuration can lead to downloads failing or not resuming correctly.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `react-native-fs` version `2.19.0` or higher to resolve `NativeEventEmitter` warnings.","message":"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.","severity":"gotcha","affected_versions":"<2.19.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Using `react-native-fs` with a React Native version that expects `NativeEventEmitter` compliance, but the installed `react-native-fs` version is too old.","error":"Invariant Violation: `new NativeEventEmitter()` was called with a non-null argument without the native module implementing `addListener` and `removeListeners`."},{"fix":"Upgrade `react-native-fs` to version `2.15.1` or higher, which includes a fix for this issue by importing `RCTImageLoaderProtocol`.","cause":"iOS build failure due to changes in React Native's internal `RCTImageLoader` import paths (specifically for RN > 0.60).","error":"Undefined symbol: _OBJC_CLASS_$_RCTImageLoader"},{"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';`.","cause":"The `RNFS` native module was not correctly linked or initialized, or the JavaScript import is incorrect.","error":"TypeError: Cannot read property 'DocumentDirectoryPath' of undefined"},{"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.","cause":"Common Android build issue, often related to AndroidX migration status or incorrect Gradle configuration.","error":"Task 'assembleRelease' failed. Android resource linking failed."}],"ecosystem":"npm"}