This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 53).
A library that provides access to the local file system on the device.
expo-file-system
provides access to files and directories stored on a device or bundled as assets into the native project. It also allows downloading files from the network.
Installation
-
npx expo install expo-file-system
If you are installing this in an existing React Native app, make sure to install expo
in your project.
Usage
import { File, Directory, Paths } from 'expo-file-system';
The File
and Directory
instances hold a reference to a file, content, or asset URI.
The file or directory does not need to exist — an error will be thrown from the constructor only if the wrong class is used to represent an existing path (so if you try to create a File
instance passing a path to an already existing directory).
Features
- Both synchronous and asynchronous, read and write access to file contents
- Creation, modification and deletion
- Available properties, such as
type
,size
,creationDate
, and more - Ability to read and write files as streams or using the
FileHandle
class - Easy file download/upload using
downloadFileAsync
orexpo/fetch
Examples
Writing and reading text files
import { File, Paths } from 'expo-file-system'; try { const file = new File(Paths.cache, 'example.txt'); file.create(); // can throw an error if the file already exists or no permission to create it file.write('Hello, world!'); console.log(file.textSync()); // Hello, world! } catch (error) { console.error(error); }
Picking files using system pickers
Usage with expo-document-picker
:
import { File } from 'expo-file-system'; import * as DocumentPicker from 'expo-document-picker'; try { const result = await DocumentPicker.getDocumentAsync({ copyToCacheDirectory: true }); const file = new File(result.assets[0]); console.log(file.textSync()); } catch (error) { console.error(error); }
Using the built-in pickFileAsync
or pickDirectoryAsync
method on Android:
import { File } from 'expo-file-system'; try { const file = new File.pickFileAsync(); console.log(file.textSync()); } catch (error) { console.error(error); }
Downloading files
Using downloadFileAsync
:
import { Directory, File, Paths } from 'expo-file-system'; const url = 'https://pdfobject.com/pdf/sample.pdf'; const destination = new Directory(Paths.cache, 'pdfs'); try { destination.create(); const output = await File.downloadFileAsync(url, destination); console.log(output.exists); // true console.log(output.uri); // path to the downloaded file, e.g., '${cacheDirectory}/pdfs/sample.pdf' } catch (error) { console.error(error); }
Or using expo/fetch
:
import { fetch } from 'expo/fetch'; import { File } from 'expo-file-system'; const url = 'https://pdfobject.com/pdf/sample.pdf'; const response = await fetch(url); const src = new File(Paths.cache, 'file.pdf'); src.write(await response.bytes());
Uploading files using `expo/fetch`
You can upload files as blobs directly with fetch
built into the Expo package:
import { fetch } from 'expo/fetch'; import { File } from 'expo-file-system'; const file = new File(Paths.cache, 'file.txt'); file.write('Hello, world!'); const response = await fetch('https://example.com', { method: 'POST', body: file, });
Or using the FormData
constructor:
import { fetch } from 'expo/fetch'; import { File, Paths } from 'expo-file-system'; const file = new File(Paths.cache, 'file.txt'); file.write('Hello, world!'); const formData = new FormData(); formData.append('data', file); const response = await fetch('https://example.com', { method: 'POST', body: formData, });
Moving and copying files
import { Directory, File, Paths } from 'expo-file-system'; try { const file = new File(Paths.document, 'example.txt'); file.create(); console.log(file.uri); // '${documentDirectory}/example.txt' file.move(Paths.cache); console.log(file.uri); // '${cacheDirectory}/example.txt' file.move(new Directory(Paths.cache, 'newFolder')); console.log(file.uri); // '${cacheDirectory}/newFolder/example.txt' } catch (error) { console.error(error); }
Using legacy FileSystem API
import * as FileSystem from 'expo-file-system/legacy'; import { File, Paths } from 'expo-file-system'; try { const file = new File(Paths.cache, 'example.txt'); const content = await FileSystem.readAsStringAsync(file.uri); console.log(content); } catch (error) { console.error(error); }
Listing directory contents recursively
import { Directory, Paths } from 'expo-file-system'; function printDirectory(directory: Directory, indent: number = 0) { console.log(`${' '.repeat(indent)} + ${directory.name}`); const contents = directory.list(); for (const item of contents) { if (item instanceof Directory) { printDirectory(item, indent + 2); } else { console.log(`${' '.repeat(indent + 2)} - ${item.name} (${item.size} bytes)`); } } } try { printDirectory(new Directory(Paths.cache)); } catch (error) { console.error(error); }
API
Classes
Type: Class extends FileSystemDirectory
Represents a directory on the filesystem.
A Directory
instance can be created for any path, and does not need to exist on the filesystem during creation.
The constructor accepts an array of strings that are joined to create the directory URI. The first argument can also be a Directory
instance (like Paths.cache
).
Example
const directory = new Directory(File.cache, "subdirName");
Directory Properties
union
A size of the directory in bytes. Null if the directory does not exist, or it cannot be read.
Acceptable values are: null
| number
string
Represents the directory URI. The field is read-only, but it may change as a result of calling some methods such as move
.
Directory Methods
Copies a directory.
void
Parameter | Type |
---|---|
options(optional) | DirectoryCreateOptions |
Creates a directory that the current uri points to.
void
Deletes a directory. Also deletes all files and directories inside the directory.
void
Retrieves an object containing properties of a directory.
DirectoryInfo
An object with directory metadata (for example, size, creation date, and so on).
Moves a directory. Updates the uri
property that now points to the new location.
void
Parameter | Type | Description |
---|---|---|
initialUri(optional) | string | An optional uri pointing to an initial folder on which the directory picker is opened. |
Type: Class extends FileSystemFile
implements Blob
Represents a file on the filesystem.
A File
instance can be created for any path, and does not need to exist on the filesystem during creation.
The constructor accepts an array of strings that are joined to create the file URI. The first argument can also be a Directory
instance (like Paths.cache
) or a File
instance (which creates a new reference to the same file).
Example
const file = new File(File.cache, "subdirName", "file.txt");
File Properties
union
A creation time of the file expressed in milliseconds since epoch. Returns null if the file does not exist, cannot be read or the Android version is earlier than API 26.
Acceptable values are: null
| number
boolean
A boolean representing if a file exists. true
if the file exists, false
otherwise.
Also, false
if the application does not have read access to the file.
union
A md5 hash of the file. Null if the file does not exist, or it cannot be read.
Acceptable values are: null
| string
union
A last modification time of the file expressed in milliseconds since epoch. Returns a Null if the file does not exist, or it cannot be read.
Acceptable values are: null
| number
number
A size of the file in bytes. 0 if the file does not exist, or it cannot be read.
string
A mime type of the file. An empty string if the file does not exist, or it cannot be read.
string
Represents the file URI. The field is read-only, but it may change as a result of calling some methods such as move
.
File Methods
The arrayBuffer()
method of the Blob interface returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer.
Promise<ArrayBuffer>
Retrieves content of the file as base64.
string
A promise that resolves with the contents of the file as a base64 string.
Retrieves content of the file as base64.
string
The contents of the file as a base64 string.
Retrieves byte content of the entire file.
Promise<Uint8Array<ArrayBuffer>>
A promise that resolves with the contents of the file as a Uint8Array.
Retrieves byte content of the entire file.
Uint8Array
A promise that resolves with the contents of the file as a Uint8Array.
Parameter | Type | Description |
---|---|---|
url | string | The URL of the file to download. |
destination | Directory | File | The destination directory or file. If a directory is provided, the resulting filename will be determined based on the response headers. |
options(optional) | DownloadOptions | - |
Parameter | Type |
---|---|
options(optional) | InfoOptions |
Retrieves an object containing properties of a file
FileInfo
An object with file metadata (for example, size, creation date, and so on).
Moves a directory. Updates the uri
property that now points to the new location.
void
Returns A FileHandle
object that can be used to read and write data to the file.
FileHandle
Parameter | Type | Description |
---|---|---|
initialUri(optional) | string | An optional URI pointing to an initial folder on which the file picker is opened. |
mimeType(optional) | string | A mime type that is used to filter out files that can be picked out. |
ReadableStream<Uint8Array<ArrayBuffer>>
Parameter | Type |
---|---|
start(optional) | number |
end(optional) | number |
contentType(optional) | string |
The slice()
method of the Blob interface creates and returns a new Blob
object which contains data from a subset of the blob on which it's called.
Blob
The stream()
method of the Blob interface returns a ReadableStream which upon reading returns the data contained within the Blob
.
ReadableStream<Uint8Array<ArrayBuffer>>
Retrieves text from the file.
Promise<string>
A promise that resolves with the contents of the file as string.
Retrieves text from the file.
string
The contents of the file as string.
WritableStream<Uint8Array>
Parameter | Type | Description |
---|---|---|
content | string | Uint8Array | The content to write into the file. |
Writes content to the file.
void
FileHandle Properties
union
A property that indicates the current byte offset in the file. Calling readBytes
or writeBytes
will read or write a specified amount of bytes starting from this offset. The offset is incremented by the number of bytes read or written.
The offset can be set to any value within the file size. If the offset is set to a value greater than the file size, the next write operation will append data to the end of the file.
Null if the file handle is closed.
Acceptable values are: null
| number
FileHandle Methods
Closes the file handle. This allows the file to be deleted, moved or read by a different process. Subsequent calls to readBytes
or writeBytes
will throw an error.
void
Parameter | Type | Description |
---|---|---|
length | number | The number of bytes to read. |
Reads the specified amount of bytes from the file at the current offset.
Uint8Array<ArrayBuffer>
Parameter | Type | Description |
---|---|---|
bytes | Uint8Array | A |
Writes the specified bytes to the file at the current offset.
void
Type: Class extends PathUtilities
Paths Properties
Record<string, Directory>
number
A property that represents the available space on device's internal storage, represented in bytes.
Directory
A property containing the bundle directory – the directory where assets bundled with the application are stored.
Directory
A property containing the cache directory – a place to store files that can be deleted by the system when the device runs low on storage.
Directory
A property containing the document directory – a place to store files that are safe from being deleted by the system.
Paths Methods
Parameter | Type | Description |
---|---|---|
path | string | File | Directory | The path to get the base name from. |
ext(optional) | string | An optional file extension. |
Returns the base name of a path.
string
A string representing the base name.
Returns the directory name of a path.
string
A string representing the directory name.
Returns the extension of a path.
string
A string representing the extension.
Parameter | Type |
---|---|
...uris | string[] |
Returns an object that indicates if the specified path represents a directory.
PathInfo
Checks if a path is absolute.
boolean
true
if the path is absolute, false
otherwise.
Joins path segments into a single path.
string
A string representing the joined path.
Normalizes a path.
string
A string representing the normalized path.
Parses a path into its components.
{
base: string,
dir: string,
ext: string,
name: string,
root: string
}
An object containing the parsed path components.
Methods
Deprecated Use
new File().copy()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
options | RelocatingOptions |
Promise<void>
Deprecated Import this method from
expo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
uri | string |
fileUri | string |
options(optional) | DownloadOptions |
callback(optional) | FileSystemNetworkTaskProgressCallback<DownloadProgressData> |
resumeData(optional) | string |
any
Deprecated Import this method from
expo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
url | string |
fileUri | string |
options(optional) | FileSystemUploadOptions |
callback(optional) | FileSystemNetworkTaskProgressCallback<UploadProgressData> |
any
Deprecated Use
new File().delete()
ornew Directory().delete()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
options(optional) | DeletingOptions |
Promise<void>
Deprecated Use
File.downloadFileAsync
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
uri | string |
fileUri | string |
options(optional) | DownloadOptions |
Promise<FileSystemDownloadResult>
Deprecated Import this method from
expo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
Promise<string>
Deprecated Use
Paths.availableDiskSpace
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Promise<number>
Deprecated Use
new File().info
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
options(optional) | InfoOptions |
Deprecated Use
Paths.totalDiskSpace
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Promise<number>
Deprecated Use
new Directory().create()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
options(optional) | MakeDirectoryOptions |
Promise<void>
Deprecated Use
new File().move()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
options | RelocatingOptions |
Promise<void>
Deprecated Use
new File().text()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
options(optional) | ReadingOptions |
Promise<string>
Deprecated Use
new Directory().list()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
Promise<string[]>
Deprecated Use
@expo/fetch
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
url | string |
fileUri | string |
options(optional) | FileSystemUploadOptions |
Promise<FileSystemUploadResult>
Deprecated Use
new File().write()
or import this method fromexpo-file-system/legacy
. This method will throw in runtime.
Parameter | Type |
---|---|
fileUri | string |
contents | string |
options(optional) | WritingOptions |
Promise<void>
Types
Property | Type | Description |
---|---|---|
idempotent(optional) | boolean | This flag controls whether the If Default: false |
intermediates(optional) | boolean | Whether to create intermediate directories if they do not exist. Default: false |
overwrite(optional) | boolean | Whether to overwrite the directory if it exists. Default: false |
Property | Type | Description |
---|---|---|
creationTime(optional) | number | A creation time of the directory expressed in milliseconds since epoch. Returns null if the Android version is earlier than API 26. |
exists | boolean | Indicates whether the directory exists. |
files(optional) | string[] | A list of file names contained within a directory. |
modificationTime(optional) | number | The last modification time of the directory expressed in milliseconds since epoch. |
size(optional) | number | The size of the file in bytes. |
uri(optional) | string | A |
Property | Type | Description |
---|---|---|
intermediates(optional) | boolean | Whether to create intermediate directories if they do not exist. Default: false |
overwrite(optional) | boolean | Whether to overwrite the file if it exists. Default: false |
Property | Type | Description |
---|---|---|
creationTime(optional) | number | A creation time of the file expressed in milliseconds since epoch. Returns null if the Android version is earlier than API 26. |
exists | boolean | Indicates whether the file exists. |
md5(optional) | string | Present if the |
modificationTime(optional) | number | The last modification time of the file expressed in milliseconds since epoch. |
size(optional) | number | The size of the file in bytes. |
uri(optional) | string | A |
Property | Type | Description |
---|---|---|
md5(optional) | boolean | Whether to return the MD5 hash of the file. Default: false |
Property | Type | Description |
---|---|---|
exists | boolean | Indicates whether the path exists. Returns true if it exists; false if the path does not exist or if there is no read permission. |
isDirectory | boolean | null | Indicates whether the path is a directory. Returns true or false if the path exists; otherwise, returns null. |