react-native-fs
![Dr. Pogodin Studio](https://raw.githubusercontent.com/birdofpreyru/react-native-fs/master/.README/logo-dr-pogodin-studio.svg)
File system access for React Native applications for Android, iOS,
Mac (Catalyst), and Windows platforms. Supports both new
and old RN architectures.
![Sponsor](https://raw.githubusercontent.com/birdofpreyru/react-native-fs/master/.README/sponsor.svg)
This is a work-in-progress fork of react-native-fs, aiming to upgrade the library to the standards of the latest React Native v0.72, with support of the New Architecture, backward compatibility to the Old Architecture, clean-up and fixes of the library API and internal implementation, and further library development following 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:
import RNFS from 'react-native-fs';
import * as RNFS from '@dr.pogodin/react-native-fs';
import {
TemporaryDirectoryPath,
writeFile,
} from '@dr.pogodin/react-native-fs';
When installing the library into a new project no additional steps are required.
IMPORTANT: Below is the original documentation for the library. It still has to be completely revised and updated. For now, for each constant / function that have been verified and tested to work in this fork there will be a VERIFIED note next to its description, certifying the state of its support in this fork.
Table of Contents
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"
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
var RNFS = require('react-native-fs');
RNFS.readDir(RNFS.MainBundlePath)
.then((result) => {
console.log('GOT RESULT', result);
return Promise.all([RNFS.stat(result[0].path), result[0].path]);
})
.then((statResult) => {
if (statResult[0].isFile()) {
return RNFS.readFile(statResult[1], 'utf8');
}
return 'no file';
})
.then((contents) => {
console.log(contents);
})
.catch((err) => {
console.log(err.message, err.code);
});
File creation
var RNFS = require('react-native-fs');
var path = RNFS.DocumentDirectoryPath + '/test.txt';
RNFS.writeFile(path, 'Lorem ipsum dolor sit amet', 'utf8')
.then((success) => {
console.log('FILE WRITTEN!');
})
.catch((err) => {
console.log(err.message);
});
File deletion
var path = RNFS.DocumentDirectoryPath + '/test.txt';
return RNFS.unlink(path)
.then(() => {
console.log('FILE DELETED');
})
.catch((err) => {
console.log(err.message);
});
File upload (Android and IOS only)
var RNFS = require('react-native-fs');
var uploadUrl = 'http://requestb.in/XXXXXXX';
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!');
};
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!');
} else {
console.log('SERVER ERROR');
}
})
.catch((err) => {
if(err.description === "cancelled") {
}
console.log(err);
});
API Reference
- Constants
- Functions
- copyFileAssets() — (Android) Copies an asset file to
the given destination.
- exists() — Checks if an item exists at the given path.
- existsAssets() — Checks if an item exists at the given path inside
the Android assets folder.
- mkdir() — Creates folder(s) at the given path.
- readDirAssets() — (Android only) Reads the content of a folder at
the given path inside the Android assets folder.
- readFile() — Reads the file at a path and return its content as
a string.
- readFileAssets() — Android-only. Reads the file at a path in
the Android app's assets folder.
and return its contents.
- Types
- Legacy — Everything else inherited from the original library,
but not yet correctly verified to work and match the documentation.
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.
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).
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).
IMPORTANT: 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
Functions
copyFileAssets()
function copyFileAssets(from: string, to: string): Promise<void>
VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.
Copies a file from the given path in the Android app's assets folder to
the specified destination path, overwriting the file at destination, if
it exists.
from
— string — Source asset path (relative to the asset
folder's root).to
— string — Destination path.- Resolves once 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.
mkdir()
function mkdir(path: string, options?: MkdirOptions): 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
— MkdirOptions | undefined — Optional.
Additional parameters.- Resolves once completed.
readDirAssets()
function readDirAssets(path: string): Promise<ReadDirItem[]>;
VERIFIED: Android. NOT SUPPORTED: iOS, macOS, Windows.
(Android only) Reads 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: 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.
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.
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
EncodingT
type EncodingT = 'ascii' | 'base64' | `utf8`;
Union of valid file encoding values.
MkdirOptions
type MkdirOptions = {
NSURLIsExcludedFromBackupKey?: boolean;
};
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.
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?
ReadFileOptionsT
type ReadFileOptionsT = {
encoding?: EncodingT;
};
The type of extra options argument of the readFile() function.
encoding
— EncodingT | undefined — Optional. File encoding.
Defaults utf8
.
WriteFileOptionsT
type WriteFileOptionsT = {
encoding?: EncodingT;
NSFileProtectionKey?: string;
};
The type of extra options argument of the writeFile() function.
Legacy
Below is the original documentation for all other methods and types inherited
from the original library. They are present in the codebase, but haven't been
tested to work after refactoring for the new version of the library, and a few
of them were commented out and marked as not yet supported on some platforms.
readDir(dirpath: string): Promise<ReadDirItem[]>
Reads the contents of path
. This must be an absolute path. Use the above path constants to form a usable file path.
The returned promise resolves with an array of objects with the following properties:
type ReadDirItem = {
ctime: date;
mtime: date;
name: string;
path: string;
size: string;
isFile: () => boolean;
isDirectory: () => boolean;
};
readdir(dirpath: string): Promise<string[]>
Node.js style version of readDir
that returns only the names. Note the lowercase d
.
stat(filepath: string): Promise<StatResult>
Stats an item at filepath
. If the filepath
is linked to a virtual file, for example Android Content URI, the originalPath
can be used to find the pointed file path.
The promise resolves with an object with the following properties:
type StatResult = {
path:
ctime: date;
mtime: date;
size: number;
mode: number;
originalFilepath: string;
isFile: () => boolean;
isDirectory: () => boolean;
};
read(filepath: string, length = 0, position = 0, encodingOrOptions?: any): Promise<string>
Reads length
bytes from the given position
of the file at path
and returns contents. encoding
can be one of utf8
(default), ascii
, base64
. Use base64
for reading binary files.
Note: reading big files piece by piece using this method may be useful in terms of performance.
readFileRes(filename:string, encoding?: string): Promise<string>
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. The file type will be detected from the extension and automatically located within res/drawable
(for image files) or res/raw
(for everything else). encoding
can be one of utf8
(default), ascii
, base64
. Use base64
for reading binary files.
Note: Android only.
appendFile(filepath: string, contents: string, encoding?: string): Promise<void>
Append the contents
to filepath
. encoding
can be one of utf8
(default), ascii
, base64
.
write(filepath: string, contents: string, position?: number, encoding?: string): Promise<void>
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. encoding
can be one of utf8
(default), ascii
, base64
.
moveFile(filepath: string, destPath: string): Promise<void>
Moves the file located at filepath
to destPath
. 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.
copyFolder(srcFolderPath: string, destFolderPath: string): Promise<void>
Copies the contents located at srcFolderPath
to destFolderPath
.
Note: Windows only. This method is recommended when directories need to be copied from one place to another.
copyFile(filepath: string, destPath: string): Promise<void>
Copies the file located at filepath
to destPath
.
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.
copyFileRes(filename: string, destPath: string): Promise<void>
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.
Note: Android only. Will overwrite destPath if it already exists.
(iOS only) copyAssetsFileIOS(imageUri: string, destPath: string, width: number, height: number, scale?: number, compression?: number, resizeMode?: string): Promise<string>
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.
Parameters
imageUri
string (required)
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 (required)
Destination to which the copied file will be saved, e.g. RNFS.TemporaryDirectoryPath + 'example.jpg'
.
width
number (required)
Copied file's image width will be resized to width
. If 0 is provided, width won't be resized.
height
number (required)
Copied file's image height will be resized to height
. If 0 is provided, height won't be resized.
scale
number (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 (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 (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.
Return value
Promise<string>
Copied file's URI.
Video-Support
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 wich
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.
(iOS only) copyAssetsVideoIOS(videoUri: string, destPath: string): Promise<string>
Not available on Mac Catalyst.
Copies a video from assets-library, that is prefixed with 'assets-library://asset/asset.MOV?...' to a specific destination.
existsRes(filename: string): Promise<boolean>
Check in the Android res folder if the item named filename
exists. res/drawable
is used as the parent folder for image files, res/raw
for everything else. If the item does not exist, return false.
Note: Android only.
hash(filepath: string, algorithm: string): Promise<string>
Reads the file at path
and returns its checksum as determined by algorithm
, which can be one of md5
, sha1
, sha224
, sha256
, sha384
, sha512
.
touch(filepath: string, mtime?: Date, ctime?: Date): Promise<string>
Sets the modification timestamp mtime
and creation timestamp ctime
of the file at filepath
. Setting ctime
is supported on iOS and Windows, android always sets both timestamps to mtime
.
downloadFile(options: DownloadFileOptions): { jobId: number, promise: Promise<DownloadResult> }
type DownloadFileOptions = {
fromUrl: string;
toFile: string;
headers?: Headers;
background?: boolean;
discretionary?: boolean;
cacheable?: boolean;
progressInterval?: number;
progressDivider?: number;
begin?: (res: DownloadBeginCallbackResult) => void;
progress?: (res: DownloadProgressCallbackResult) => void;
resumable?: () => void;
connectionTimeout?: number
readTimeout?: number
backgroundTimeout?: number
};
type DownloadResult = {
jobId: number;
statusCode: number;
bytesWritten: number;
};
Download file from options.fromUrl
to options.toFile
. Will overwrite any previously existing file.
If options.begin
is provided, it will be invoked once upon download starting when headers have been received and passed a single argument with the following properties:
type DownloadBeginCallbackResult = {
jobId: number;
statusCode: number;
contentLength: number;
headers: Headers;
};
If options.progress
is provided, it will be invoked continuously and passed a single argument with the following properties:
type DownloadProgressCallbackResult = {
jobId: number;
contentLength: number;
bytesWritten: number;
};
If options.progressInterval
is provided, it will return progress events in the maximum frequency of progressDivider
.
For example, if progressInterval
= 100, you will not receive callbacks more often than every 100th millisecond.
If options.progressDivider
is provided, it will return progress events that divided by progressDivider
.
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.
(IOS only): options.background
(Boolean
) - Whether to continue downloads when the app is not focused (default: false
)
This option is currently only available for iOS, see the Background Downloads Tutorial (iOS) section.
(IOS only): If options.resumable
is provided, it will be invoked when the download has stopped and and can be resumed using resumeDownload()
.
stopDownload(jobId: number): void
Abort the current download job with this ID. The partial file will remain on the filesystem.
(iOS only) resumeDownload(jobId: number): void
Resume the current download job with this ID.
(iOS only) isResumable(jobId: number): Promise<bool>
Check if the the download job with this ID is resumable with resumeDownload()
.
Example:
if (await RNFS.isResumable(jobId) {
RNFS.resumeDownload(jobId)
}
(iOS only) completeHandlerIOS(jobId: number): void
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.
uploadFiles(options: UploadFileOptions): { jobId: number, promise: Promise<UploadResult> }
options
(Object
) - An object containing named parameters
type UploadFileOptions = {
toUrl: string;
binaryStreamOnly?: boolean
files: UploadFileItem[];
headers?: Headers;
fields?: Fields;
method?: string;
begin?: (res: UploadBeginCallbackResult) => void;
progress?: (res: UploadProgressCallbackResult) => void;
};
type UploadResult = {
jobId: number;
statusCode: number;
headers: Headers;
body: string;
};
Each file should have the following structure:
type UploadFileItem = {
name: string;
filename: string;
filepath: string;
filetype: string;
};
If options.begin
is provided, it will be invoked once upon upload has begun:
type UploadBeginCallbackResult = {
jobId: number;
};
If options.progress
is provided, it will be invoked continuously and passed a single object with the following properties:
type UploadProgressCallbackResult = {
jobId: number;
totalBytesExpectedToSend: number;
totalBytesSent: number;
};
Percentage can be computed easily by dividing totalBytesSent
by totalBytesExpectedToSend
.
(iOS only) stopUpload(jobId: number): Promise<void>
Abort the current upload job with this ID.
getFSInfo(): Promise<FSInfoResult>
Returns an object with the following properties:
type FSInfoResult = {
totalSpace: number;
freeSpace: number;
};
(Android only) scanFile(path: string): Promise<string[]>
Scan the file using Media Scanner.
(Android only) getAllExternalFilesDirs(): Promise<string[]>
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.
(iOS only) pathForGroup(groupIdentifier: string): Promise<string>
groupIdentifier
(string
) Any value from the com.apple.security.application-groups entitlements list.
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.
Background Downloads Tutorial (iOS)
Background downloads in iOS require a bit of a setup.
First, in your AppDelegate.m
file add the following:
#import <RNFSManager.h>
...
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)())completionHandler
{
[RNFSManager 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.