react-native-fs2

A fork of react-native-fs with a smaller footprint and fixes due to the upstream library seemingly being abandoned.

Why the fork?

This library intentional or not has become critical to the success of our mobile applications. We've noticed a few things that led to this fork:

• The original library continuing to expand beyond a basic file system library.
• Hundreds of open issues
• Pull requests go unmerged
• Tests that go untouched
• Some edge case bugs that stay unresolved

We debated a few paths, but we felt it best to fork the project and make some major changes that will upset some.

• We dropped Windows support.
• We dropped methods specific to platforms.
• We dropped upload support.

We will continue to support this library for as long as we use it.

Installation

npm i --save react-native-fs2

Supported React Native Versions

| react-native-fs2 | react-native | |------------------|--------------| | 3.0.x | >=0.69 |

Changelog

Changes can be found in CHANGELOG.md

Usage

import RNFS from 'react-native-fs2';

console.log(await RNFS.getFSInfo());

mkdir

// mkdir(filepath: string, options?: MkdirOptions): Promise<undefined>
await RNFS.mkdir(`FolderToCreate`);

• Creates directory at filepath location.
• Optionally include MkdirOptions with properties:
  • (iOS) - NSURLIsExcludedFromBackupKey
  • (iOS) - NSFileProtectionKey

moveFile

// moveFile(filepath: string, destPath: string, options?: FileOptions): Promise<undefined>
await RNFS.moveFile('FileToMove', 'DestinationLocation')

• Moves file from filepath to destPath
• Optionally includes FileOptions with properties:
  • (iOS) - NSFileProtectionKey

copyFile

// copyFile(filepath: string, destPath: string, options?: FileOptions): Promise<undefined>
await RNFS.copyFile('FileToCopy', 'DestinationLocation')

• Copies file from filepath to destPath
• Optionally includes FileOptions with properties:
  • (iOS) - NSFileProtectionKey

getFSInfo

// getFSInfo(): Promise<FSInfoResult>
const fsInfo = await RNFS.getFSInfo()

• Returns an FSInfoResult object that contains information on the device storage space
• FSInfoResult
  • totalSpace: number -> The total amount of storage space on the device (in bytes).
  • freeSpace: number -> The amount of available storage space on the device (in bytes)

getAllExternalFilesDirs (Android only)

// getAllExternalFilesDirs(): Promise<string[]>
const externalFileDirs = await RNFS.getAllExternalFilesDirs()

• Returns an array with the absolute paths to application-specific directories on all shared/external storage devices where the application can place persistent files it owns.

unlink

// unlink(filepath: string): Promise<void>
await RNFS.unlink('FileToUnlink')

• Unlinks the item at filepath. If the item does not exist, an error will be thrown. Also recursively deletes directories (works like Linux rm -rf).

exists

// exists(filepath: string): Promise<boolean>
await RNFS.exists('File')

• Check if the item exists at filepath. If the item does not exist, return false.

completeHandlerIOS (iOS Only)

// completeHandlerIOS(jobId: number): void
await RNFS.completeHandler('JobID')

• Tell iOS you are done handling a completed download when using background downloads.

readDir

// readDir(dirPath: string): Promise<ReadDirItem[]>
const dirItems = await RNFS.readDir('DirPath')

• Retuns an array of ReadDirItem which are items that are present in the directory
• ReadDirItem
  • ctime: Date | undefined -> The creation date of the file (iOS only)
  • mtime: Date | undefined -> The last modified date of the file
  • name: string -> The name of the item
  • path: string -> The absolute path to the item
  • size: number -> Size in bytes
  • isFile: () => boolean -> Is the file just a file?
  • isDirectory: () => boolean -> Is the file a directory?

readFile

// readFile(filepath: string, encodingOrOptions?: EncodingOrOptions): Promise<string>
const fileData = await RNFS.readFile('DirPath', 'utf8')

• Reads the filepath and return the file contents
• Optionally includes EncodingOrOptions with values:
  • 'utf8' (default) | 'base64' (for binary files) | 'ascii' | 'arraybuffer'
  • ...fileoptions
• Note: arraybuffer requires react-native-blob-jsi-helper
  • npm i react-native-blob-jsi-helper or yarn add react-native-blob-jsi-helper

read

/*
  read(
    filepath: string,
    length: number = 0,
    position: number = 0,
    encodingOrOptions?: EncodingOrOptions
  ): Promise<string>
*/

const fileData = await RNFS.read('FileToRead', 0, 0, 'utf8')

• Reads bytes length from the given position of the file at filepath and returns the file contents.
• Optionally includes EncodingOrOptions with values:
  • 'utf8' (default) | 'base64' (for binary files) | 'ascii'
  • ...fileoptions

hash

// hash(filepath: string, algorithm: string): Promise<string>
const fileChecksum = await RNFS.hash('FileToHash', 'md5')

• Reads the filepath and returns its checksum as determined by algorithm, which can be one of the following md5 | sha1 | sha224 | sha256 | sha384 | sha512.

writeFile

// writeFile(filepath: string, contents: string, encodingOrOptions?: EncodingOrOptions): Promise<void>
await RNFS.write('FileToWrite', 'ContentsToWrite', 'utf8')

• Write the contents to filepath
• Optionally includes EncodingOrOptions with values:
  • 'utf8' (default) | 'base64' (for binary files) | 'ascii'
  • ...fileoptions

appendFile

// appendFile(filepath: string, contents: string, encodingOrOptions?: EncodingOrOptions): Promise<void>
await RNFS.appendFile('FileToWrite', 'ContentsToAppend', 'utf8')

• Append the contents to filepath
• Optionally includes EncodingOrOptions with values:
  • 'utf8' (default) | 'base64' (for binary files) | 'ascii'
  • ...fileoptions

write

// write(filepath: string, contents: string, position?: number, encodingOrOptions?: EncodingOrOptions): Promise<void>
await RNFS.write('FileToWrite', 'ContentsToWrite', -1, 'utf8')

• Write the contents to filepath at the given random access position. When position is undefined or -1 the contents is appended to the end of the file
• Optionally includes EncodingOrOptions with values:
  • 'utf8' (default) | 'base64' (for binary files) | 'ascii'
  • ...fileoptions

stat

// stat(filepath: string): Promise<StatResult>
const fileStats = await RNFS.stat('FilePath')

• Retuns an array of StatResult which are statistics of the file
• StatResult
  • path: string -> The same as filepath argument
  • ctime: date -> The creation date of the file
  • mtime: date -> The last modified date of the file
  • size: number -> Size in bytes
  • mode: number -> UNIX file mode
  • originalFilepath: string -> Android: In case of content uri this is the pointed file path, otherwise is the same as path
  • isFile: () => boolean -> Is the file just a file?
  • isDirectory: () => boolean -> Is the file a directory?

downloadFile

// downloadFile(options: DownloadFileOptions): { jobId: number, promise: Promise<DownloadResult> }
const downloadResults = await RNFS.downloadFile('FilePath')

• Downloads file from options.fromUrl to options.toFile. Will overwrite any previously existing file.
• Include DownloadFileOptions with properties
  • fromUrl: string -> URL to download file from
  • toFile: string -> Local filesystem path to save the file to
  • headers?: Headers -> An object of headers to be passed to the server
  • background?: boolean -> Continue the download in the background after the app terminates (iOS only)
  • discretionary?: boolean -> Allow the OS to control the timing and speed of the download to improve perceived performance (iOS only)
  • cacheable?: boolean
  • progressInterval?: number
  • progressDivider?: number
  • begin?: (res: DownloadBeginCallbackResult) => void; -> Note: it is required when progress prop provided
  • progress?: (res: DownloadProgressCallbackResult) => void;
  • resumable?: () => void -> only supported on iOS
  • connectionTimeout?: number -> only supported on Android
  • readTimeout?: number -> supported on Android and iOS
  • backgroundTimeout?: number -> Maximum time (in milliseconds) to download an entire resource (iOS only, useful for timing out background downloads)
• Returns DownloadResult
  • jobId: number -> The download job ID, required if one wishes to cancel the download. See stopDownload.
  • statusCode: number -> The HTTP status code
  • bytesWritten: number -> The number of bytes written to the file

stopDownload

// stopDownload(jobId: number): void
await RNFS.stopDownload('JobID'): void

• Abort the current download job with this ID. The partial file will remain on the filesystem.

resumeDownload (iOS Only)

// resumeDownload(jobId: number): void
await RNFS.resumeDownload('JobID'): void

• Resume the current download job with this ID

isResumable (iOS Only)

// isResumable(jobId: number): Promise<bool>
if (await RNFS.isResumable('JobID')) {
    RNFS.resumeDownload('JobID')
}

• Check if the the download job with this ID is resumable.

touch

// touch(filepath: string, mtime?: Date, ctime?: Date): Promise<void>
await RNFS.touch('FilePath', Date, Date)

• Sets the modification timestamp mtime and creation timestamp ctime of the file at filepath. Setting ctime is only supported on iOS, Android always sets both timestamps to mtime.

scanFile (Android Only)

// scanFile(path: string): Promise<string[]>
await RNFS.scanFile('FilePath', Date, Date)

• Scan the file using Media Scanner.

MediaStore

RNFS2 can now interact with the MediaStore on Android. This allows you to add, delete, and update media files in the MediaStore.

Inspiration for this feature came from react-native-blob-util

This feature is only available on Android targeting API 29 or higher. And may require the following permissions:

<!-- Required only if your app needs to access images or photos that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

<!-- Required only if your app needs to access videos that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

<!-- Required only if your app needs to access audio files that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" />

Available Methods

createMediaFile

• Creates a new media file in the MediaStore with the given mimeType. This will not create a file on the filesystem, but will create a reference in the MediaStore.

// createMediaFile(fileDescriptor: FileDescriptor, mediatype: MediaCollections): Promise<string>

const fileDescriptor = { name: 'sample', parentFolder: 'MyAppFolder', mimeType: 'image/png' }

const contentURI = await RNFS.MediaStore.createMediaFile(fileDescriptor,  RNFS.MediaStore.MEDIA_IMAGE)

updateMediaFile

• Updates the media file in the MediaStore

// updateMediaFile(uri: string, fileDescriptor: FileDescriptor, mediatype: MediaCollections): Promise<string>

const contentURI = 'content://media/external/images/media/123'
const fileDescriptor = { name: 'sample-updated-filename', parentFolder: 'MyAppFolder', mimeType: 'image/png' }

const contentURI = await RNFS.MediaStore.updateMediaFile(contentURI, fileDescriptor, RNFS.MediaStore.MEDIA_IMAGE)

writeToMediaFile

• Writes data to a media file in the MediaStore with the given mimeType.

// writeToMediaFile((uri: string, path: string): Promise<void>

await RNFS.MediaStore.writeToMediaFile('content://media/external/images/media/123', '/path/to/image/imageToWrite.png')

copyToMediaStore

• Copies the file at filepath to the MediaStore with the given mimeType.

// copyToMediaStore(fileDescriptor: filedescriptor, mediatype: MediaCollections, path: string): Promise<string>

const fileDescriptor = { name: 'sample', parentFolder: 'MyAppFolder', mimeType: 'image/png' }

const contentURI = await RNFS.MediaStore.copyToMediaStore(fileDescriptor,  RNFS.MediaStore.MEDIA_IMAGE, '/path/to/image/imageToCopy.png')

queryMediaStore

• Queries the MediaStore for media files with the given searchOptions.

// queryMediaStore(searchOptions: MediaStoreSearchOptions): Promise<MediaStoreQueryResult>

await RNFS.MediaStore.queryMediaStore({
  uri: 'content://media/external/images/media/123',
  fileName: ''
  relativePath: ''
  mediaType: RNFS.MediaStore.MEDIA_IMAGE;
})

// or
await RNFS.MediaStore.queryMediaStore({
  uri: '',
  fileName: 'image.png'
  relativePath: 'MyAppFolder'
  mediaType: RNFS.MediaStore.MEDIA_IMAGE;
})

deleteFromMediaStore

• Deletes the media file at uri from the MediaStore.

// deleteFromMediaStore(uri: string): Promise<boolean>

await RNFS.MediaStore.deleteFromMediaStore('content://media/external/images/media/123')

FileDescriptor

type FileDescriptor = { 
  name: string; 
  parentFolder: string; 
  mimeType: string 
};

MediaStoreSearchOptions

type MediaStoreSearchOptions = { 
  uri: string; 
  fileName: string; 
  relativePath: string; 
  mediaType: MediaCollections 
};

MediaStoreQueryResult

type MediaStoreQueryResult = { 
  contentUri: string;
};

MediaStore Collections

• MediaStore.MEDIA_AUDIO - Audio media collection
• MediaStore.MEDIA_IMAGE - Image media collection
• MediaStore.MEDIA_VIDEO - Video media collection
• MediaStore.MEDIA_DOWNLOAD - Download media collection

Constants

Common

• CachesDirectoryPath - Absolute path to cache directory.
• DocumentDirectoryPath - Absolute path to the document directory.
• TemporaryDirectoryPath - Absolute path to temporary directory (cache on Android).

Android

• ExternalCachesDirectoryPath - Absolute path to the external cache directory.
• ExternalDirectoryPath - Absolute path to external shared directory.
• ExternalStorageDirectoryPath - Absolute path to the external shared storage directory.
• DownloadDirectoryPath - Absolute path to the download directory.

Please be sure to request needed permissions via PermissionsAndroid.

iOS

• LibraryDirectoryPath - Absolute path to NSLibraryDirectory
• MainBundlePath - Absolute path to main bundle directory.