@dr.pogodin/react-native-fs

v2.30.1

Published

21 days ago

Native filesystem access for React Native

Downloads

24,594

0High
0Medium
0Low

dr.pogodin

react-native ios android fs filesystem download upload file-transfer

React Native File System

File system access for React Native applications for Android, iOS, Mac (Catalyst), and Windows platforms. Supports both new and old RN architectures.

Contributors

+ contributors of the original react-native-fs

Getting Started
Project History & Roadmap
Background Downloads Tutorial (iOS)
Examples
API Reference
- Constants
  - CachesDirectoryPath — The absolute path to the caches directory.
  - DocumentDirectoryPath — The absolute path to the document directory.
  - DownloadDirectoryPath — (Android & Windows) The absolute path to the download directory (on android and Windows only).
  - ExternalCachesDirectoryPath — (Android) The absolute path to the external caches directory.
  - ExternalDirectoryPath — (Android) The absolute path to the external files, shared directory.
  - ExternalStorageDirectoryPath — (Android) The absolute path to the external storage, shared directory.
  - LibraryDirectoryPath — (iOS) The absolute path to the NSLibraryDirectory.
  - MainBundlePath — (non-Android) The absolute path to the main bundle directory.
  - PicturesDirectoryPath — The absolute path to the pictures directory.
  - RoamingDirectoryPath — (Windows) The absolute path to the roaming directory.
  - TemporaryDirectoryPath — The absolute path to the temporary directory.
- Functions
  - appendFile() — Appends content to a file.
  - completeHandlerIOS() — For use when using background downloads, tell iOS you are done handling a completed download.
  - copyAssetsFileIOS() — Reads an image file from Camera Roll and writes it to the specified location. It also can be used to get video thumbnails.
  - copyAssetsVideoIOS() — Copies a video from the assets-library to the specified destination.
  - copyFile() — Copies a file (or a folder with files - except on Android/Windows) to a new destination.
  - copyFileAssets() — (Android only) Copies Android app's asset(s) to the specified destination.
  - copyFileRes() — (Android only) Copies specified resource to the given destination.
  - copyFolder() — (Windows only) Copies a folder to a new location in a Windows-efficient way.
  - downloadFile() — Downloads a file from network.
  - exists() — Checks if an item exists at the given path.
  - existsAssets() — (Android only) Checks if an item exists at the given path inside the Android assets folder.
  - existsRes() — (Android only) Checks if the resource exists.
  - hash() — Calculates file hash.
  - isResumable() — (iOS only) Check if the the download job with this ID is resumable with resumeDownload().
  - getAllExternalFilesDirs() — (Android only) 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.
  - getFSInfo() — Gets info on the free and total storage space on the device, and its external storage.
  - mkdir() — Creates folder(s) at the given path.
  - moveFile() — Moves a file (or a folder with files - except on Windows) to a new location.
  - pathForGroup() — (iOS only) Returns the absolute path to the directory shared for all applications with the same security group identifier.
  - pickFile() — Prompts user to select file(s) with help of a platform-provided file picker UI.
  - read() — Reads a fragment of file content.
  - readdir() — Lists the content of a folder (names only).
  - readDir() — Lists the content of a folder (with item details).
  - readDirAssets() — (Android only) Lists the content of a folder at the given path inside the Android assets folder.
  - readFile() — Reads entire file content.
  - readFileAssets() — (Android only) Reads the file at a path in the Android app's assets folder.
  - readFileRes() — (Android only) Reads specified file in the Android app's resource folder and return its contents.
  - resumeDownload() — (iOS only) Resume an interrupted download job.
  - scanFile() — (Android-only) Scan the file using Media Scanner.
  - stat() — Returns info on a file system item.
  - stopDownload() — Aborts a file download job.
  - stopUpload() — (iOS only) Aborts file upload job.
  - touch() — Alters creation and modification timestamps of the given file.
  - unlink() — Unlinks (removes) a file or directory with files. and return its contents.
  - uploadFiles() — Uploads files to a remote location.
  - write() — Writes content to a file at the given random access position.
  - writeFile() — Writes content into a file.
- Types
  - DownloadBeginCallbackResultT — The type of argument passed to begin callback in DownloadFileOptionsT.
  - DownloadFileOptionsT — Options for downloadFile().
  - DownloadProgressCallbackResultT — The type of argument passed to the progress callback in DownloadFileOptionsT.
  - DownloadResultT — Return type of downloadFile().
  - EncodingT — Union of valid file encoding values.
  - FileOptionsT — Extra options for copyFile().
  - FSInfoResultT — The type of result resolved by getFSInfo().
  - MkdirOptionsT — Extra options for mkdir().
  - PickFileOptionsT — Optional parameters for pickFile().
  - ReadDirResItemT — Elements returned by readDir().
  - ReadDirAssetsResItemT — Elements returned by readDirAssets().
  - ReadFileOptionsT — The type of extra options argument of the readFile() function.
  - StatResultT — The type of result resolved by stat().
  - StringMapT — Just a simple string-to-string mapping.
  - UploadBeginCallbackArgT — The type of begin callback argument in UploadFileOptionsT.
  - UploadFileItemT — The type of files elements in UploadFileOptionsT objects.
  - UploadFileOptionsT — Options for uploadFiles().
  - UploadProgressCallbackArgT — The type of progress callback argument in UploadFileOptionsT, and a few other places.
  - UploadResultT — The type of resolved uploadFiles() promise.
  - WriteFileOptionsT — The type of extra options argument of the writeFile() function.

Getting Started

Just install & use:

$ npm install --save @dr.pogodin/react-native-fs

Note: Windows auto-link command (at least as it was needed for example project to install the lib hosted in the parent folder):

npx react-native autolink-windows --sln "windows\ReactNativeFsExample.sln" --proj "windows\ReactNativeFsExample\ReactNativeFsExample.vcxproj"

Project History & Roadmap

This project is a fork of the upstream react-native-fs library, which has been abandoned by its owners and maintainers. This forks aims to keep the library on par with the latest React Native standards, with support of the New Architecture, backward compatibility with the Old Architecture; and to further develop the library according to the best industry practices.

To migrate from the legacy react-native-fs install this fork_

npm install --save @dr.pogodin/react-native-fs

then upgrade its imports in the code:

// The legacy RNFS was imported like this:
import RNFS from 'react-native-fs';

// Instead, this fork should be imported like this:
import * as RNFS from '@dr.pogodin/react-native-fs';
// or (preferrably) you should import separate constants / functions you need
// like:
import {
  TemporaryDirectoryPath,
  writeFile,
} from '@dr.pogodin/react-native-fs';

ROADMAP:

v2.22.0 of this library is mostly a drop-in replacement for the latest (v2.20.0) release of the original, upstream react-native-fs. It requires to upgrade the host project to the latest RN v0.73+, and to correct the names of TypeScript types exported from the library, if they are used, by appending letter T to all of them. Beside these, the library has its functionality and API matching the original library, with just a handful of internal fixes, and a few added features.
In further versions, v2.X.Y, we'll be taking care of improvements, and optimizations of existing functionality, as well as adding new APIs, and deprecating old ones (without yet dropping them out of the codebase), with the ultimate goal to release v3 version of the library.
The aims for v3 release are the following:
- To unify library APIs for all platforms — the current library has a lots of platform-dependent APIs, which goes against the purpose and spirit of React Native — we'll abstract out and unify everything that is possible, to allow smooth cross-plaform ride.
- To make library API closer to Node's File System API.
- To ensure that library has no intrinsic limitations (like now it is not efficient for handling large files, etc.)

Background Downloads Tutorial (iOS)

Background downloads in iOS require a bit of a setup.

First, in your AppDelegate.m file add the following:

#import <RNFSBackgroundDownloads.h>

...

- (void)application:(UIApplication *)application
  handleEventsForBackgroundURLSession:(NSString *)identifier
  completionHandler:(void (^)())completionHandler
{
  [RNFSBackgroundDownloads
    setCompletionHandlerForIdentifier:identifier
    completionHandler:completionHandler];
}

The handleEventsForBackgroundURLSession method is called when a background download is done and your app is not in the foreground.

We need to pass the completionHandler to RNFS along with its identifier.

The JavaScript will continue to work as usual when the download is done but now you must call RNFS.completeHandlerIOS(jobId) when you're done handling the download (show a notification etc.)

BE AWARE! iOS will give about 30 sec. to run your code after handleEventsForBackgroundURLSession is called and until completionHandler is triggered so don't do anything that might take a long time (like unzipping), you will be able to do it after the user re-launces the app, otherwide iOS will terminate your app.

Examples

These are legacy examples, and should be revised, there is an Example app in the /example folder of the codebase, you probably should rather check it than these examples.

Basic

// require the module
var RNFS = require('react-native-fs');

// get a list of files and directories in the main bundle
RNFS.readDir(RNFS.MainBundlePath) // On Android, use "RNFS.DocumentDirectoryPath" (MainBundlePath is not defined)
  .then((result) => {
    console.log('GOT RESULT', result);

    // stat the first file
    return Promise.all([RNFS.stat(result[0].path), result[0].path]);
  })
  .then((statResult) => {
    if (statResult[0].isFile()) {
      // if we have a file, read it
      return RNFS.readFile(statResult[1], 'utf8');
    }

    return 'no file';
  })
  .then((contents) => {
    // log the file contents
    console.log(contents);
  })
  .catch((err) => {
    console.log(err.message, err.code);
  });

File creation

// require the module
var RNFS = require('react-native-fs');

// create a path you want to write to
// :warning: on iOS, you cannot write into `RNFS.MainBundlePath`,
// but `RNFS.DocumentDirectoryPath` exists on both platforms and is writable
var path = RNFS.DocumentDirectoryPath + '/test.txt';

// write the file
RNFS.writeFile(path, 'Lorem ipsum dolor sit amet', 'utf8')
  .then((success) => {
    console.log('FILE WRITTEN!');
  })
  .catch((err) => {
    console.log(err.message);
  });

File deletion

// create a path you want to delete
var path = RNFS.DocumentDirectoryPath + '/test.txt';

return RNFS.unlink(path)
  .then(() => {
    console.log('FILE DELETED');
  })
  // `unlink` will throw an error, if the item to unlink does not exist
  .catch((err) => {
    console.log(err.message);
  });

File upload (Android and IOS only)

// require the module
var RNFS = require('react-native-fs');

var uploadUrl = 'http://requestb.in/XXXXXXX';  // For testing purposes, go to http://requestb.in/ and create your own link
// create an array of objects of the files you want to upload
var files = [
  {
    name: 'test1',
    filename: 'test1.w4a',
    filepath: RNFS.DocumentDirectoryPath + '/test1.w4a',
    filetype: 'audio/x-m4a'
  }, {
    name: 'test2',
    filename: 'test2.w4a',
    filepath: RNFS.DocumentDirectoryPath + '/test2.w4a',
    filetype: 'audio/x-m4a'
  }
];

var upload
= (response) => {
  var jobId = response.jobId;
  console.log('UPLOAD HAS BEGUN! JobId: ' + jobId);
};

var uploadProgress = (response) => {
  var percentage = Math.floor((response.totalBytesSent/response.totalBytesExpectedToSend) * 100);
  console.log('UPLOAD IS ' + percentage + '% DONE!');
};

// upload files
RNFS.uploadFiles({
  toUrl: uploadUrl,
  files: files,
  method: 'POST',
  headers: {
    'Accept': 'application/json',
  },
  fields: {
    'hello': 'world',
  },
  begin: uploadBegin,
  progress: uploadProgress
}).promise.then((response) => {
    if (response.statusCode == 200) {
      console.log('FILES UPLOADED!'); // response.statusCode, response.headers, response.body
    } else {
      console.log('SERVER ERROR');
    }
  })
  .catch((err) => {
    if(err.description === "cancelled") {
      // cancelled by user
    }
    console.log(err);
  });

API Reference

Constants

CachesDirectoryPath

const CachesDirectoryPath: string;

VERIFIED: Android, iOS, macOS, Windows.

The absolute path to the caches directory.

DocumentDirectoryPath

const DocumentDirectoryPath: string;

VERIFIED: Android, iOS, macOS, Windows.

The absolute path to the document directory.

IMPORTANT: DocumentDirectoryPath (iOS) will include an ID in the path that changes each build e.g ...Application/BCE32988-4C51-483B-892B-16671E3771C2/Documents.

Use relative paths and resolve the full path at runtime to avoid files not being found on new builds.

DownloadDirectoryPath

const DownloadDirectoryPath: string;

VERIFIED: Android, Windows. NOT SUPPORTED: iOS, macOS.

The absolute path to the download directory (on android and Windows only).

ExternalCachesDirectoryPath

const ExternalCachesDirectoryPath: string;

VERIFIED: Android, Windows (empty?). NOT SUPPORTED: iOS, macOS.

The absolute path to the external caches directory (android only).

ExternalDirectoryPath

const ExternalDirectoryPath: string;

VERIFIED: Android, iOS (empty?), macOS (empty?), Windows.

The absolute path to the external files, shared directory (android only).

ExternalStorageDirectoryPath

const ExternalStorageDirectoryPath: string;

VERIFIED: Android, iOS (empty?), macOS (empty?), Windows (empty?).

The absolute path to the external storage, shared directory (android only).

BEWARE: When using ExternalStorageDirectoryPath it's necessary to request permissions (on Android) to read and write on the external storage, here an example: React Native Offical Doc

LibraryDirectoryPath

const LibraryDirectoryPath: string;

VERIFIED: iOS, macOS, Windows (empty?). NOT SUPPORTED: Android.

The absolute path to the NSLibraryDirectory (iOS only).

MainBundlePath

const MainBundlePath: string;

VERIFIED: iOS, macOS, Windows. NOT SUPPORTED: Android.

The absolute path to the main bundle directory (not available on Android).

PicturesDirectoryPath

const PicturesDirectoryPath: string;

VERIFIED: Android, Windows. NOT SUPPORTED: iOS, macOS.

The absolute path to the pictures directory.

RoamingDirectoryPath

const RoamingDirectoryPath: string;

VERIFIED: Windows. NOT SUPPORTED: Android, iOS, macOS.

The absolute path to the roaming directory (Windows only).

TemporaryDirectoryPath

const TemporaryDirectoryPath: string;

VERIFIED: Android, iOS, macOS, Windows.

The absolute path to the temporary directory (falls back to Caching-Directory on Android).

BEWARE: The trailing slash might be inconsistent in this path! At the very least, on Android this constant does not have a slash in the end; but on iOS (new arch) it has it. It is something to unify in future.

Functions

appendFile()

function appendFile(filepath: string, contents: string, encoding?: string): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows.

Appends content to a file.

filepath — string — File path.
contents — string — The content to add.
encoding — EncodingT — Optional. Encoding.
Resolves once the operation has been completed.

completeHandlerIOS()

function completeHandlerIOS(jobId: number): void;

VERIFIED: well... not really verified, but is callable on iOS.

iOS only. For use when using background downloads, tell iOS you are done handling a completed download.

Read more about background downloads in the Background Downloads Tutorial (iOS) section.

copyAssetsFileIOS()

function copyAssetsFileIOS(
  imageUri: string,
  destPath: string,
  width: number,
  height: number,
  scale?: number,
  compression?: number,
  resizeMode?: string,
): Promise<string>;

BEWARE: After ensuring this method gets called correctly on iOS, calling it just crashes the example app for me. Though, I don't have much interest to dig into it now (not for free :)

iOS only.

Not available on Mac Catalyst.

Reads an image file from Camera Roll and writes to destPath. This method assumes the image file to be JPEG file. This method will download the original from iCloud if necessary.

One can use this method also to create a thumbNail from a video in a specific size. Currently it is impossible to specify a concrete position, the OS will decide which Thumbnail you'll get then. To copy a video from assets-library and save it as a mp4-file, refer to copyAssetsVideoIOS.

Further information: https://developer.apple.com/reference/photos/phimagemanager/1616964-requestimageforasset The promise will on success return the final destination of the file, as it was defined in the destPath-parameter.

imageUri — string — URI of a file in Camera Roll.
Can be either of the following formats:
- ph://CC95F08C-88C3-4012-9D6D-64A413D254B3/L0/001
- assets-library://asset/asset.JPG?id=CC95F08C-88C3-4012-9D6D-64A413D254B3&ext=JPG
destPath — string — Destination to which the copied file will be saved, e.g. RNFS.TemporaryDirectoryPath + 'example.jpg'.
width — number — Copied file's image width will be resized to width. If 0 is provided, width won't be resized.
height — number — Copied file's image height will be resized to height. If 0 is provided, height won't be resized.
scale — number | undefined — Optional. Copied file's image will be scaled proportional to scale factor from width x height. If both width and height are 0, the image won't scale. Range is [0.0, 1.0] and default is 1.0.
compression — number | undefined — Optional. Quality of copied file's image. The value 0.0 represents the maximum compression (or lowest quality) while the value 1.0 represents the least compression (or best quality). Range is [0.0, 1.0] and default is 1.0.
resizeMode — string | undefined — Optional. If resizeMode is 'contain', copied file's image will be scaled so that its larger dimension fits width x height. If resizeMode is other value than 'contain', the image will be scaled so that it completely fills width x height. Default is 'contain'. Refer to PHImageContentMode.
Resolves to string — Copied file's URI.

copyAssetsVideoIOS()

function copyAssetsVideoIOS(videoUri: string, destPath: string): Promise<string>;

BEWARE: Similarly to copyAssetsFileIOS() I believe it gets correctly called on iOS, but it crashes the example app in my naive test. Perhaps I use it wrong, or something should be patched in the original implementation.

Not available on Mac Catalyst.

Copies a video from assets-library, that is prefixed with 'assets-library://asset/asset.MOV?...' to a specific destination.

videoUri — string — Video URI.
destPath — string — Destination.
Resolves to string — copied file path?

copyFile()

function copyFile(from: string, into: string, options?: FileOptionsT): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows.

Copies a file to a new destination. Throws if called on a directory.

Note: On Android and Windows copyFile() will overwrite destPath if it already exists. On iOS an error will be thrown if the file already exists. — beware, this has not been verified yet.

BEWARE: On Android and Windows copyFile() throws if called on a folder; on other platforms it does not throw, but it has not been verified yet, if it actually copies a folder with all its content there.

from — string — Source path.
into — string — Destination path.
options — FileOptionsT | undefined — Optional. Additional settings. beware, it has not been verified they work, yet.
Resolves once done.

copyFileAssets()

function copyFileAssets(from: string, into: string): Promise<void>

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Copies Android app's asset(s) to the specified destination.

If from points to a file, this function assumes into is a file path as well, and it copies the asset to that destination, overwriting the existing file at that destination, if any.

If from points to a folder, this function assumes into is a folder path as well, and it recursively copies the content of from into that destination, preserving the folder structure of copied assets, and overwriting existing files in the destination in case of conflicts. It does not clean the destination prior to copying into it, and it cannot overwrite files by folders and vice-versa. If into does not exist, it will be created, assuming its parent folder does exist (i.e. it does not attempt to create entire path as mkdir() does).

from — string — Source path, relative to the root assets folder. Can be empty to refer the root assets folder itself.
into — string — Destination path.
Resolves once completed.

copyFileRes()

function copyFileRes(filename: string, destPath: string): Promise<void>

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. Copies the file named filename in the Android app's res folder and copies it to the given destPath path. res/drawable is used as the source parent folder for image files, res/raw for everything else.

BEWARE: It will overwrite destPath if it already exists.

filename — string — Resource name.
destPath — string — Destination.
Resolves once completed.

copyFolder()

copyFolder(from: string, into: string): Promise<void>;

VERIFIED: Windows NOT SUPPORTED: Android, iOS, macOS

Windows only. Copies content to a new location in a Windows-efficient way, compared to copyFile().

from — string — Source location.
into — string — Destination location.

downloadFile()

function downloadFile(options: DownloadFileOptionsT): {
  jobId: number;
  promise: Promise<DownloadResultT>;
};

VERIFIED: Android, iOS, macOS, Windows
BEWARE: Only basic functionality has been verified.

Downloads a file from options.fromUrl to options.toFile. It Will overwrite any previously existing file.

options — DownloadFileOptionsT — Download settings.
Returns an object holding jobId number (can be used to manage in-progress download by corresponding functions) and promise resolving to DownloadResultT once the download is completed.

exists()

function exists(path: string): Promise<boolean>;

VERIFIED: Android, iOS, macOS, Windows.

Checks if an item exists at the given path.

path — string — Path.
Resolves to true if the item exists; to false otherwise.

existsAssets()

function existsAssets(path: string): Promise<boolean>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. Checks if an item exists at the given path in the Android assets folder.

path — string — Path, relative to the root of the Android assets folder.
Resolves true if the item exists; false otherwise.

existsRes()

function existsRes(filename: string): Promise<boolean>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. Check if the specified resource exists. res/drawable is used as the parent folder for image files, res/raw for everything else.

filename — string — Resource name.
Resolves to boolean — true if the resource exists; false otherwise.

getAllExternalFilesDirs()

function getAllExternalFilesDirs(): Promise<string[]>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. 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.

Resolves to string[] — the array of external paths.

getFSInfo()

function getFSInfo(): Promise<FSInfoResultT>;

VERIFIED: Android, iOS, macOS, Windows.

Provides information about free and total file system space.

Resolves to an FSInfoResultT object.

hash()

function hash(path: string, algorithm: string): Promise<string>;

VERIFIED: Android, iOS, macOS, Windows.

Calculates file's hash.

path — string — File path.
algorithm — string — One of md5, sha1, sha224 (currently it does not work on Windows!), sha256, sha384, sha512.
Resolves to string — file hash.

isResumable()

function isResumable(jobId: number): Promise<bool>;

iOS only. Check if the the download job with this ID is resumable with resumeDownload().

Example:

if (await RNFS.isResumable(jobId) {
    RNFS.resumeDownload(jobId)
}

jobId — number — Download job ID.
Resolves to boolean — the result.

mkdir()

function mkdir(path: string, options?: MkdirOptionsT): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows.

Creates folder(s) at path, and does not throw if already exists (similar to mkdir -p in Linux).

path — string — Path to create.
options — MkdirOptionsT | undefined — Optional. Additional parameters.
Resolves once completed.

moveFile()

function moveFile(from: string, into: string): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows.

Moves an item (a file, or a folder with files) to a new location. This is more performant than reading and then re-writing the file data because the move is done natively and the data doesn't have to be copied or cross the bridge.

Note: Overwrites existing file in Windows — To be verified, how does it behave on other systems, and whether it really overwrites items on Windows?

BEWARE: On Android, if from is a folder, rather than moving entire folder with its content inside the into folder, it moves the content of from inside into.

BEWARE: On Windows it currently does not allow moving folders with files, on other platforms it works fine.

from — string — Old path of the item.
into — string — New path of the item.
Resolves once the operation is completed.

pathForGroup()

function pathForGroup(groupIdentifier: string): Promise<string>;

VERIFIED: iOS.

iOS only. Returns the absolute path to the directory shared for all applications with the same security group identifier. This directory can be used to to share files between application of the same developer.

Invalid group identifier will cause a rejection.

For more information read the Adding an App to an App Group section.

groupIdentifier — string — Any value from the com.apple.security.application-groups entitlements list.
Resolves to string — the result path.

pickFile()

function pickFile(options?: PickFileOptionsT): Promise<string[]>;

SUPPORTED: Android, iOS, macOS, Windows.

Prompts the user to select file(s) using a platform-provided file picker UI, which also allows to access files outside the app sandbox.

BEWARE: On windows the options differ from the other platform since the native file piper doesn't support mimeTypes but fileExtensions and different picker types like singleFile, multipleFIle and folder. For more information see PickFileOptionsT.

BEWARE: On macOS (Catalyst) for this function to work you MUST go to Signing & Capabilities settings of your project, and inside its App Sandbox section to set File Access > User Selected Files to Read/Write value (with just Read the file picker on macOS opens and seemingly works, but rather than returning the picked up URL, it signals the operation has been cancelled). If it is left at the default None value the call to pickFile() will crash the app.

options — PickFileOptionsT — Optional parameters. By default, this function allows user to select a single file of any kind.
Resolves to a string array — URIs (paths) of user-selected files, allowing a direct access to them with other methods in this library (e.g. readFile()), even if the file is outside the app sandbox.
NOTE: On iOS & macOS it resolve to special values with the format «bookmark://<BASE64_ENCODED_STRING>», rather than normal URIs. It is necessary for the support of security scopes (see Bookmarks and Security Scopes) in library methods. The «<BASE64_ENCODED_STRING>» in this case is a Base64-encoded binary representation of the URL bookmark, along with its security scope data. Other methods of the library are expected to automatically handle such special URIs as needed.
BEWARE: It has not been thoroughly verified yet that all library methods support these «Bookmark URLs» correctly. The expected error in such case is a failure to access the URLs as non-existing.

read()

function read(path: string, length = 0, position = 0, encodingOrOptions?: EncodingT | ReadFileOptionsT): Promise<string>;

VERIFIED: Android, iOS, macOS, Windows.

Reads length bytes from the given position of a file.

BEWARE: On Android and Windows read() called with zero length and position resolves to empty string; however on other platforms it resolves to the entire file content (same as readFile()). This behavior has been inherited from the legacy RNFS implementation, and is to be corrected in future.

Note: To read entire file at once consider to use readFile() instead.

Note: No matter the encoding, this function will always read the specified number of bytes from the given position, and then transform that byte chunk into a string using the given encoding; that is in constrast of, say, reading the given number of characters, if utf8 is given.

path — string — File path.
length — number | undefined — Optional. The number of bytes to read. Defaults 0.
position — number | undefined — Optional. The starting read position, in bytes. Defaults 0.
encodingOrOptions — EncodingT | ReadFileOptionsT | undefined — Optional. The encoding to use, or additional read options (currently, the encoding is the only option anyway). Defaults utf8.
Resolves to string — the content read from file, transformed into the string according to the specified encoding.

readdir()

function readdir(path: string): Promise<string[]>;

VERIFIED: Android, iOS, macOS.

Lists the content of given folder (names only — NodeJS-style). Note the lowercase d in the name, unlike in readDir().

BEWARE: There is no guarantees about the sort order of resolved listing.

path — string — Folder path.
Resolves to a string array — the names of items in the folder.

readDir()

function readDir(path: string): Promise<ReadDirItem[]>;

VERIFIED: Android, iOS, macOS, Windows.

Lists the content of given absolute path.

BEWARE: There is no guarantees about the sort order of resolved listing.

BEWARE: On Windows the isDirectory() and isFile() methods of result currently return false for all items; also size value in the result is platform dependent for directories.

path — string — Path.
Resolves to an array of ReadDirResItemT objects.

readDirAssets()

function readDirAssets(path: string): Promise<ReadDirItem[]>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

(Android only) Lists the content of a folder at the given path inside the Android assets folder.

path — string — Folder path, relative to the root of the assets folder.
Resolves to an array of ReadDirAssetsResItemT objects.

readFile()

function readFile(path: string, encodingOrOptions?: EncodingT | ReadFileOptionsT): Promise<string>;

VERIFIED: Android, iOS, macOS, Windows.

Reads the file at path and return its content as a string.

Note: To read a selected fragment of the file see read().

Note: For base64 encoding this function will return file content encoded into Base64 format; for ascii it will fill each character of the result string with the code of corresponding byte in the file; and for utf8 (default) it will assume the source file is UTF8-encoded, and it will decode it into the result string (thus each result character will be corresponding to a group of 1-to-4 bytes of the source file).

BEWARE: You will take quite a performance hit if you are reading big files.

path — string — File path.
encoding — EncodingT | ReadFileOptionsT — Optional. File encoding, or extra options.
Resolves to string — the content read from the file, and transformed according to the given encoding.

readFileAssets()

function readFileAssets(path: string, encoding?: EncodingT | ReadFileOptionsT): Promise<string>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. Reads the file at path in the Android app's assets folder and return its contents. encoding can be one of utf8 (default), ascii, base64. Use base64 for reading binary files.

path — string — Asset path.
encoding — EncodingT | ReadFileOptionsT | undefined — Optional. Encoding, or extra options object, which currently only supports specifying the encoding.
Resolves to string — the asset content.

readFileRes

function readFileRes(filename: string, encoding?: EncodingT): Promise<string>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. Reads the file named filename in the Android app's res folder and return contents. Only the file name (not folder) needs to be specified.

Original docs say: The file type will be detected from the extension and automatically located within res/drawable (for image files) or res/raw (for everything else). Good luck with it. The test in the example app does not work if the file extension is not included into the filename... but perhaps I've overlooked something.

filename — string — Resouce file name.
encoding — EncodingT — Optional Encdoing.
Resolves to string — the resource content.

resumeDownload()

function resumeDownload(jobId: number): void;

iOS only. Resume the current download job with this ID.

jobId — number — Download job ID.

scanFile()

function scanFile(path: string): Promise<string | null>;

VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.

Android-only. Scan the file using Media Scanner.

path — string — Path of the file to scan.
Resolve to string or null — URI of for the file if the scanning operation succeeded and the file was added to the media database; or null if scanning failed.

stat()

function stat(path: string): Promise<StatResultT>;

VERIFIED: Android, iOS, macOS, Windows.

Stats an item at path. If the path is linked to a virtual file, for example Android Content URI, the originalPath can be used to find the pointed file path (beware — this has not been verified yet).

BEWARE: On Windows a bunch of stuff in the response is currently not compatible with the specs — size is a string rather than number, isDirectory() and isFile() do not work (always return false), etc. Also on Windows, even with those defects accounted for the test for this function tends to randomly fail on a regular basis. It thus requires more troubleshooting, but it is not a priority for now.

path — string — Item path.
Resolves to a StatResultT object.

stopDownload()

function stopDownload(jobId: number): void;

VERIFIED: Android, iOS.

Aborts a file download job. The partial file will remain on the filesystem, and the promise returned from the aborted downloadFile() call will reject with an error.

jobId — number — Download job ID (see downloadFile()).

stopUpload()

function stopUpload(jobId: number): void;

VERIFIED: iOS. NOT SUPPORTED: Android, Windows.

iOS only. Abort the current upload job with given ID.

NOTE: Unlike stopDownload() it does not cause the pending upload promise to reject. Perhaps, we'll change it in future to behave similarly.

jobId — number — Upload job ID.

touch()

function touch(filepath: string, mtime?: Date, ctime?: Date): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows.

Alters creation and modification timestamps of the given file.

filepath — string — File path.
mtime — Date | undefined — Optional. Modification timestamp.
ctime — Date | undefined — Optional. Creation timestamp. It is supported on iOS and Windows; Android always sets both timestamps equal mtime.
Resolves once done.

unlink()

function unlink(path: string): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows.

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

path — string — Item path.
Resolves once done.

uploadFiles()

function uploadFiles(options: UploadFileOptionsT): {
  jobId: number;
  promise: Promise<UploadResultT>;
}

VERIFIED: Android, iOS, macOS, Windows

Uploads files to a remote location.

BEWARE: Only the most basic upload functionality has been tested so far in this library fork.

options — UploadFileOptionsT — Upload settings.
Returns an object holding jobId number (can be used to manage in-progress uploads by corresponding functions), and promise resolving to UploadResultT once the upload completes successfully. In case the upload fails (including when it fails due to HTTP errors), the promise is rejected with Error object, to which .result field an instance of UploadResultT is attached, if HTTP response was received.

write()

function write(filepath: string, contents: string, position?: number, encoding?: EncodingT): Promise<void>;

VERIFIED: Android, iOS, macOS, Windows

Writes content to a file at the given random access position.

filepath — string — File path.
contents — string — Content to write.
position — number | undefined — Write position. If undefined or -1 the contents is appended to the end of the file.
encoding — EncodingT — Write encoding.
Resolves once the operation has been completed.

writeFile()

function writeFile(path: string, content: string, encodingOrOptions?: EncodingT | WriteFileOptionsT): Promise<void>

VERIFIED: Android, iOS, macOS, Windows.

Write the content to the file at path, overwritting it if exists already.

NOTE: With base64 encoding value this function will assume that given content is Base64-encoded already, and it will be decoded into the file; for ascii encoding each character of content will be written to one byte in the file, and the function will fail if any character is outside the U+0000 to U+00FF range (keep in mind, that regular JS strings have two-byte characters); and for utf8 encoding (default) it will encode content characters (which can be from U+0000 to U+FFFF in this case) into the corresponding UTF8 code (i.e. each source character will be turned into a group of 1-to-4 bytes in the written file).

path — string — File path.
content — string — Data to write into the file.
encodingOrOptions — EncodingT | WriteFileOptionsT — Data encoding, or extra options.
Resolves once completed.

Types

DownloadBeginCallbackResultT

type DownloadBeginCallbackResultT = {
  jobId: number;
  statusCode: number;
  contentLength: number;
  headers: Headers;
};

The type of argument passed to begin callback in DownloadFileOptionsT.

jobId — number — The download job ID, required if one wishes to cancel the download. See stopDownload().
statusCode — number — The HTTP status code.
contentLength — number — The total size in bytes of the download resource.
headers — StringMapT — The HTTP response headers from the server.

DownloadFileOptionsT

type DownloadFileOptions = {
  fromUrl: string;
  toFile: string;
  headers?: StringMapT;
  background?: boolean;
  discretionary?: boolean;
  cacheable?: boolean;
  progressInterval?: number;
  progressDivider?: number;
  begin?: (res: DownloadBeginCallbackResultT) => void;
  progress?: (res: DownloadProgressCallbackResultT) => void;
  resumable?: () => void;
  connectionTimeout?: number;
  readTimeout?: number;
  backgroundTimeout?: number;
};

The type of options argument of downloadFile().

fromUrl — string — URL to download file from.
toFile — string — Local filesystem path to save the file to.
headers — StringMapT — Optional. An object of headers to be passed to the server.
background — boolean — Optional. Continue the download in the background after the app terminates (iOS only). See Background Downloads Tutorial (iOS). Defaults false.
discretionary — boolean — Optional. Allow the OS to control the timing and speed of the download to improve perceived performance. This setting may prevent downloading with mobile internet or when the battery is low. Only works when background is activated (iOS only, defaults to false).
cacheable — boolean — Optional. Whether the download can be stored in the shared NSURLCache (iOS only, defaults to true).
progressInterval — number Optional. If provided, the download progress events will be emitted with the maximum frequency of progressInterval.
For example, if progressInterval = 100, you will not receive callbacks more often than every 100th millisecond.
progressDivider — number Optional. If provided, the download progress events are emitted at progressDivider number of steps.
For example, if progressDivider = 10, you will receive only ten callbacks for this values of progress: 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100. Use it for performance issues.
If progressDivider = 0, you will receive all progressCallback calls, default value is 0.
begin — (res: DownloadBeginCallbackResultT) => void — Optional; required if progress prop provided. If provided, it is invoked when download starts, once headers have been received, and it is passed a single argument of DownloadBeginCallbackResultT type.
progress — (res: DownloadProgressCallbackResultT) => void — Optional. If provided, it is being invoked continuously and passed in a single argument of DownloadProgressCallbackResultT type.
resumable — () => void — Optional. iOS-only. If provided, it is invoked when the download has stopped and and can be resumed using resumeDownload().
connectionTimeout — number — Optional. Only supported on Android yet.
readTimeout — number Optional. Supported on Android and iOS.
backgroundTimeout — number — Optional. Maximum time (in milliseconds) to download an entire resource (iOS only, useful for timing out background downloads).

DownloadProgressCallbackResultT

type DownloadProgressCallbackResultT = {
  jobId: number;
  contentLength: number;
  bytesWritten: number;
};

The type of argument passed to the progress callback in DownloadFileOptionsT.

jobId — number The download job ID, required if one wishes to cancel the download. See stopDownload().
contentLength — number — The total size in bytes of the download resource.
bytesWritten — number — The number of bytes written to the file so far.

DownloadResultT

type DownloadResultT = {
  jobId: number;
  statusCode: number;
  bytesWritten: number;
};

Return type of downloadFile().

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.

EncodingT

type EncodingT = 'ascii' | 'base64' | `utf8`;

Union of valid file encoding values.

FileOptionsT

type FileOptionsT = {
  // iOS-specific.
  NSFileProtectionKey?: string;
};

The type of additional options for copyFile().

NSFileProtectionKey — string | undefined — Optional. iOS-only. See https://developer.apple.com/documentation/foundation/nsfileprotectionkey

FSInfoResultT

type FSInfoResultT = {
  freeSpace: number;
  freeSpaceEx: number;
  totalSpace: number;
  totalSpaceEx: number;
};

The type of result resolved by getFSInfo().

freeSpace — number — Free storage space on the device, in bytes.
totalSpace — number — The total storage space on the device, in bytes.

BEWARE: The following values have been seen reported on Android, but they are not reported on iOS, probably neither on other systems, and they should be further checked / fixed.

freeSpaceEx — number — Free storage space in the external storage, in bytes.
totalSpaceEx — number — The total storage space in the external storage, in bytes.

MkdirOptionsT

type MkdirOptionsT = {
  NSURLIsExcludedFromBackupKey?: boolean; // iOS only
};

Type of extra options argument for mkdir().

NSURLIsExcludedFromBackupKey — boolean | undefined — (iOS only) The property can be provided to set this attribute on iOS platforms. Apple will reject apps for storing offline cache data that does not have this attribute.

PickFileOptionsT

type PickFileOptionsT = {
  mimeTypes?: string[];
  pickerType?: 'singleFile' | 'multipleFiles' | 'folder';
  fileExtensions?: FileExtension[]
};

Optional parameters for pickFile() function.

mimeTypes — string[] — [Android - iOS - macOS] Optional. An array of MIME types of files user is allowed to select. Defaults to ['*/*'] allowing to select any file.
pickerType — 'singleFile' | 'multipleFiles' | 'folder' — [Windows] Optional. The type of objects to pick can be either a single file, multiple files or one folder.
- Multiple folders are not supported by windows.
- Defaults to 'singleFile' */
fileExtensions — FileExtension[] — [Windows] Optional, The file extensions to pick from.
- Only applies to pickerType !== 'folder'
- Defaults to [] (all file extensions) */
- FileExtension = ´.${string}´ - e.g '.bmp', '.mp3'

ReadDirAssetsResItemT

type ReadDirAssetsResItemT = {
  name: string;
  path: string;
  size: string;
  isFile: () => boolean;
  isDirectory: () => boolean;
};

Type of result elements returned by the readDirAssets() function.

name — string — Item name.
path — string — Item path.
size — string — Size in bytes. Note that the size of files compressed during the creation of the APK (such as JSON files) cannot be determined. size will be set to -1 in this case.
isFile — () => boolean — Is this item a regular file?
isDirectory — () => boolean — Is this item a directory?

ReadDirResItemT

type ReadDirResItemT = {
  ctime: Date | null;
  mtime: Date;
  name: string;
  path: string;
  size: number;
  isFile: () => boolean;
  isDirectory: () => boolean;
};

The type of objects returned by the readDir() function.

ctime — Date | null — Item creation date (iOS only; null on other platforms).
isDirectory — () => boolean — Evaluates true if item is a folder; false otherwise.
isFile — () => boolean — Evaluates true if item is a file; false otherwise.
mtime — Date — The last modified date of the item.
name — string — Name of the item.
path — string — Absolute path of the item.
size — number — Item size in bytes.

ReadFileOptionsT

type ReadFileOptionsT = {
  encoding?: EncodingT;
};

The type of extra options argument of the readFile() function.

encoding — EncodingT | undefined — Optional. File encoding. Defaults utf8.

StatResultT

type StatResultT = {
  ctime: Date;
  isDirectory: () => boolean;
  isFile: () => boolean;
  mode: undefined;
  mtime: Date;
  originalFilepath: string;
  path: string;
  size: number;
};

The type of result resolved by stat().

ctime — Date — Item's creation date.
isDirectory — () => boolean — Evaluates true if the item is a folder; false otherwise.
isFile — () => boolean — Evaluates true if the item is a file; false otherwise.
~~mode — number | undefined — UNIX file mode; undefined on platforms that currnetly do not support it.~~
NOTE: In the library v2.29.0 the support of this field for iOS / macOS (the only platforms that provided it before) was dropped; thus it is now undefined on all platforms.
mtime — Date — Item's last modification date.
originalFilepath — string — (Android-only) In case of content uri this is the pointed file path, otherwise is the same as path.
path — string — Item path.
size — number — Item size in bytes.

StringMapT

type StringMapT = { [key: string]: string };

Just a simple string-to-string mapping.

UploadBeginCallbackArgT

type UploadBeginCallbackArgT = {
  jobId: number;
};

The type of begin callback argument in UploadFileOptionsT.

jobId — number — The upload job ID, required if one wishes to cancel the upload. See stopUpload().

UploadFileItemT

type UploadFileItemT = {
  name?: string;
  filename: string;
  filepath: string;
  filetype?: string;
};

The type of files elements in UploadFileOptionsT objects.

name — string | undefined — Optional Name of the file, if not defined then filename is used.
filename — string — Name of file.
filepath — string — Path to file.
filetype — string | undefined — Optional. The mimetype of the file to be uploaded, if not defined it will get mimetype from filepath extension.

UploadFileOptionsT

type UploadFileOptionsT = {
  toUrl: string;
  binaryStreamOnly?: boolean;
  files: UploadFileItem[];
  headers?: StringMapT;
  fields?: StringMapT;
  method?: string;
  begin?: (res: UploadBeginCallbackArgT) => void;
  progress?: (res: UploadProgressCallbackArgT) => void;
};

Type of options object in uploadFiles() function.

toUrl — string — URL to upload file to.
binaryStreamOnly — boolean | undefined — Optional. Allow for binary data stream for file to be uploaded without extra headers. Defaults false.
files — UploadFileItemT[] — An array of objects with the file information to be uploaded.
headers — StringMapT | undefined — Optional. An object of headers to be passed to the server.
fields — StringMapT | undefined — Optional. An object of fields to be passed to the server.
method — string | undefined — Optional. Defaults POST, supports POST and PUT.
begin — (res: UploadBeginCallbackArgT) => void — Optional. If provided, it will be invoked once upon upload has begun.
progress — (res: UploadProgressCallbackArgT) => void — Optional. If provided, it will be invoked continuously and passed a single object of UploadProgressCallbackArgT type.

UploadProgressCallbackArgT

type UploadProgressCallbackArgT = {
  jobId: number;
  totalBytesExpectedToSend: number;
  totalBytesSent: number;
};

The type of progress callback argument in UploadFileOptionsT.

Percentage can be computed easily by dividing totalBytesSent by totalBytesExpectedToSend.

jobId — number — The upload job ID, required if one wishes to cancel the upload. See stopUpload().
totalBytesExpectedToSend number — The total number of bytes that will be sent to the server
totalBytesSent — number — The number of bytes sent to the server

UploadResultT

type UploadResultT = {
  jobId: number;
  statusCode: number;
  headers: StringMapT;
  body: string;
};

The type of resolved uploadFiles() promise.

jobId — number — The upload job ID, required if one wishes to cancel the upload. See stopUpload().
statusCode — number — The HTTP status code.
headers — StringMapT — The HTTP response headers from the server.
body — string — The HTTP response body.

WriteFileOptionsT

type WriteFileOptionsT = {
  encoding?: EncodingT;
  NSFileProtectionKey?: string;
};

The type of extra options argument of the writeFile() function.

encoding — EncodingT | undefined — Optional. File encoding to use. Defaults utf8.
NSFileProtectionKey — string | undefined — Optional. iOS-only. See: https://developer.apple.com/documentation/foundation/nsfileprotectionkey

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

React Native File System

Sponsored By

Contributors

Table of Contents

Getting Started

Project History & Roadmap

Background Downloads Tutorial (iOS)

Examples

Basic

File creation

File deletion

File upload (Android and IOS only)

API Reference

Constants

CachesDirectoryPath

DocumentDirectoryPath

DownloadDirectoryPath

ExternalCachesDirectoryPath

ExternalDirectoryPath

ExternalStorageDirectoryPath

LibraryDirectoryPath

MainBundlePath

PicturesDirectoryPath

RoamingDirectoryPath

TemporaryDirectoryPath

Functions

appendFile()

completeHandlerIOS()

copyAssetsFileIOS()

copyAssetsVideoIOS()

copyFile()

copyFileAssets()

copyFileRes()

copyFolder()

downloadFile()

exists()

existsAssets()

existsRes()

getAllExternalFilesDirs()

getFSInfo()

hash()

isResumable()

mkdir()

moveFile()

pathForGroup()

pickFile()

read()

readdir()

readDir()

readDirAssets()

readFile()

readFileAssets()

readFileRes

resumeDownload()

scanFile()

stat()

stopDownload()

stopUpload()

touch()

unlink()

uploadFiles()

write()

writeFile()

Types

DownloadBeginCallbackResultT

DownloadFileOptionsT

DownloadProgressCallbackResultT

DownloadResultT

EncodingT

FileOptionsT

FSInfoResultT

MkdirOptionsT

PickFileOptionsT

ReadDirAssetsResItemT