This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 52).
A library that provides access to the local file system on the device.
Thenext
version of the FileSystem API is included in theexpo-file-system
library. It can be used alongside the previous API, and offers a simplified, object oriented way of performing filesystem operations.
expo-file-system/next
provides access to the file system stored locally on the device. It can also download files from the network.
To provide quicker updates,expo-file-system/next
is currently unsupported in Expo Go and Snack. To use it, create a development build.
-Â
npx expo install expo-file-system
If you are installing this in an existing React Native app, start by installing expo
in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.
import { File, Paths } from 'expo-file-system/next';
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.text()); // Hello, world!
} catch (error) {
console.error(error);
}
import { File, Paths } from 'expo-file-system/next';
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);
}
import { File, Paths } from 'expo-file-system/next';
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);
}
import { FileSystem } from 'expo-file-system';
import { File, Paths } from 'expo-file-system/next';
try {
const file = new File(Paths.cache, 'example.txt');
const content = await FileSystem.readAsStringAsync(file.uri);
console.log(content);
} catch (error) {
console.error(error);
}
import { Directory, Paths } from 'expo-file-system/next';
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);
}
Directory
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.
Directory Properties
exists
boolean
A boolean representing if a directory exists. true
if the directory exists, false
otherwise.
Also false
if the application does not have read access to the file.
uri
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
create(options)
Parameter | Type |
---|---|
options (optional) | CreateOptions |
Creates a directory that the current uri points to.
void
delete()
Deletes a directory. Also deletes all files and directories inside the directory.
void
move(destination)
Moves a directory. Updates the uri
property that now points to the new location.
any
File
Type: Class extends FileSystemFile
File Properties
exists
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.
md5
null | string
An md5 hash of the file. Null if the file does not exist or it cannot be read.
size
null | number
A size of the file in bytes. Null if the file does not exist or it cannot be read.
type
null | string
A mime type of the file. Null if the file does not exist or it cannot be read.
uri
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
base64()
Retrieves content of the file as base64.
string
The contents of the file as a base64 string.
blob()
Returns the file as a Blob. The blob can be used in @expo/fetch
to send files over network and for other uses.
bytes()
Retrieves byte content of the entire file.
The contents of the file as a Uint8Array.
downloadFileAsync(url, destination)
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. |
A static method that downloads a file from the network.
A promise that resolves to the downloaded file.
Example
const file = await File.downloadFileAsync("https://example.com/image.png", new Directory(Paths.document));
move(destination)
Moves a directory. Updates the uri
property that now points to the new location.
any
open()
Returns a FileHandle object that can be used to read and write data to the file.
write(content)
Parameter | Type | Description |
---|---|---|
content | string | Uint8Array | The content to write into the file. |
Writes content to the file.
void
Paths
Type: Class extends PathUtilities
Paths Properties
Paths Methods
basename(path, ext)
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.
dirname(path)
Returns the directory name of a path.
string
A string representing the directory name.
extname(path)
Returns the extension of a path.
string
A string representing the extension.
isAbsolute(path)
Checks if a path is absolute.
boolean
true
if the path is absolute, false
otherwise.
join(...paths)
Joins path segments into a single path.
string
A string representing the joined path.
normalize(path)
Normalizes a path.
string
A string representing the normalized path.
parse(path)
Parses a path into its components.
{
base: string,
dir: string,
ext: string,
name: string,
root: string
}
An object containing the parsed path components.
relative(from, to)
Parameter | Type | Description |
---|---|---|
from | string | File | Directory | The base path. |
to | string | File | Directory | The relative path. |
Resolves a relative path to an absolute path.
string
A string representing the resolved path.