Filesystem access for React Native
MIT License
Filesystem access for React Native. Supports saving network requests directly to the filesystem. Supports Android scoped storage, a requirement when targeting API 30 or higher.
npm install react-native-file-access
cd ios && pod install
Apple restricts usage of certain privacy sensitive API calls. If you do not use disk space measurements or file timestamps, define the following variable in your Podfile to exclude restricted API calls. More details.
$RNFANoPrivacyAPI = true
If the app does not use autolinking, continue to the manual install instructions in the wiki.
React Native | react-native-file-access |
---|---|
<= 0.64 | 1.x.x |
0.65+, old arch | 2.x.x, 3.x.x |
0.71+, new arch | 3.x.x |
import { Dirs, FileSystem } from 'react-native-file-access';
// ...
const text = await FileSystem.readFile(Dirs.CacheDir + '/test.txt');
Dirs.CacheDir
Dirs.DatabaseDir
(Android only)Dirs.DocumentDir
Dirs.LibraryDir
(iOS & MacOS only)Dirs.MainBundleDir
Dirs.SDCardDir
(Android only)
FileSystem.cpExternal()
when possible.FileSystem.appendFile(path: string, data: string, encoding?: 'utf8' | 'base64'): Promise<void>
data
is assumed utf8.FileSystem.concatFiles(source: string, target: string): Promise<number>
FileSystem.cp(source: string, target: string, onProgress?: (bytesCopied: number, contentLength: number, done: boolean) => void): Promise<void>
FileSystem.cpAsset(asset: string, target: string, type?: 'asset' | 'resource'): Promise<void>
type
is asset
. Prefer this when possible.resource
uses the Android res/
folder, and inherits the associatedFileSystem.cpExternal(source: string, targetName: string, dir: 'audio' | 'downloads' | 'images' | 'video'): Promise<void>
Dirs.DocumentDir
with UIFileSharingEnabled
LSSupportsOpeningDocumentsInPlace
enabled.FileSystem.df(): Promise<{ internal_free: number, internal_total: number, external_free?: number, external_total?: number }>
FileSystem.exists(path: string): Promise<boolean>
FilesSystem.fetch(
resource: string,
init: { body?: string, headers?: { [key: string]: string }, method?: string, network?: 'any' | 'unmetered', path?: string },
onProgress?: (bytesRead: number, contentLength: number, done: boolean) => void
): Promise<FetchResult>
type FetchResult = {
headers: { [key: string]: string };
ok: boolean;
redirected: boolean;
status: number;
statusText: string;
url: string;
}
resource
- URL to fetch.init.path
- Optional filesystem location to save the response.init.network
- Optional restriction on network type. Specifyingunmetered
will reject the request if unmetered connections (most likelyonProgress
- Optional callback to listen to download progress. Eventsdone
becoming true
.contentLength
is only accurate if the server sends the correct headers.FilesSystem.fetchManaged(
resource: string,
init: { body?: string, headers?: { [key: string]: string }, method?: string, network?: 'any' | 'unmetered', path?: string },
onProgress?: (bytesRead: number, contentLength: number, done: boolean) => void
): ManagedFetchResult
type ManagedFetchResult = {
cancel: () => Promise<void>;
result: Promise<FetchResult>;
}
fetch()
, with the option to cancel before completion.FilesSystem.getAppGroupDir(groupName: string): Promise<string>
FilesSystem.hash(path: string, algorithm: 'MD5' | 'SHA-1' | 'SHA-224' | 'SHA-256' | 'SHA-384' | 'SHA-512'): Promise<string>
FilesSystem.isDir(path: string): Promise<boolean>
FileSystem.ls(path: string): Promise<string[]>
FileSystem.mkdir(path: string): Promise<string>
FileSystem.mv(source: string, target: string): Promise<void>
FileSystem.readFile(path: string, encoding?: 'utf8' | 'base64'): Promise<string>
FileSystem.readFileChunk(path: string, offset: number, length: number, encoding?: 'utf8' | 'base64'): Promise<string>
offset
, reading for length
bytes.
FileSystem.stat(path: string): Promise<FileStat>
type FileStat = {
filename: string;
lastModified: number;
path: string;
size: number;
type: 'directory' | 'file';
}
FileSystem.statDir(path: string): Promise<FileStat[]>
FileSystem.unlink(path: string): Promise<void>
FileSystem.unzip(source: string, target: string): Promise<void>
FileSystem.writeFile(path: string, data: string, encoding?: 'utf8' | 'base64'): Promise<void>
data
is assumed utf8.Util.basename(path: string, separator?: string): string
separator
is /
.Util.dirname(path: string, separator?: string): string
separator
is /
.Util.extname(path: string, separator?: string): string
separator
is /
.For simple usage, use FileSystem.cpExternal()
to submit files to general
scoped storage categories.
Most functions in this library work with content://
Android resource uris.
To gain access to a resource uri, currently use a library such as
react-native-document-picker or
react-native-scoped-storage.
Eventually this library will incorporate file/folder selector functionality
(pull requests welcome).
Note:
AndroidScoped.appendPath(dir, 'data.txt')
, not dir + '/data.txt'
.AndroidScoped.appendPath(basePath: string, segment: string): string
For ease of testing, this library contains a mock implementation:
jest/react-native-file-access.ts.
To use, copy it into the __mocks__
folder, modifying if needed.
This library aims to be a modern implementation of filesystem api, using Kotlin/Swift and latest best practices. For a more established library, consider:
For more greater control over network requests, consider react-native-blob-courier.
See the contributing guide to learn how to contribute to the repository and the development workflow.
MIT