This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 52).

Expo FileSystem (next) iconExpo FileSystem (next)

GitHub

npm

A library that provides access to the local file system on the device.

Android
iOS
tvOS

The next version of the FileSystem API is included in the expo-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.

Installation

Terminal
- 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.

Usage

Writing and reading text files

example.ts
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);
}

Downloading files

example.ts
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);
}

Moving and copying files

example.ts
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);
}

Using legacy FileSystem API

example.ts
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);
}

Listing directory contents recursively

example.ts
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);
}

API

Classes

Android
iOS
tvOS

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

Android
iOS
tvOS

exists

Type: 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.

Android
iOS
tvOS

uri

Read Only • Type: string

Represents the directory URI. The field is read-only, but it may change as a result of calling some methods such as move.

Android
iOS
tvOS

name

Type: string

Directory name.

Android
iOS
tvOS

parentDirectory

Type: Directory

Directory containing the file.

Directory Methods

Android
iOS
tvOS

copy(destination)

ParameterType
destinationDirectory | File

Copies a directory.

Returns:

any

Android
iOS
tvOS

create(options)

ParameterType
options
(optional)
CreateOptions

Creates a directory that the current uri points to.

Returns:

void

Android
iOS
tvOS

delete()

Deletes a directory. Also deletes all files and directories inside the directory.

Returns:

void

Android
iOS
tvOS

move(destination)

ParameterType
destinationDirectory | File

Moves a directory. Updates the uri property that now points to the new location.

Returns:

any

Android
iOS
tvOS

File

Type: Class extends FileSystemFile

File Properties

Android
iOS
tvOS

exists

Type: 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.

Android
iOS
tvOS

md5

Type: null | string

An md5 hash of the file. Null if the file does not exist or it cannot be read.

Android
iOS
tvOS

size

Type: null | number

A size of the file in bytes. Null if the file does not exist or it cannot be read.

Android
iOS
tvOS

type

Type: null | string

A mime type of the file. Null if the file does not exist or it cannot be read.

Android
iOS
tvOS

uri

Read Only • Type: string

Represents the file URI. The field is read-only, but it may change as a result of calling some methods such as move.

Android
iOS
tvOS

extension

Type: string

File extension.

Example

Android
iOS
tvOS

name

Type: string

File name. Includes the extension.

Android
iOS
tvOS

parentDirectory

Type: Directory

Directory containing the file.

File Methods

Android
iOS
tvOS

base64()

Retrieves content of the file as base64.

Returns:

string

The contents of the file as a base64 string.

Android
iOS
tvOS

blob()

Returns the file as a Blob. The blob can be used in @expo/fetch to send files over network and for other uses.

Returns:

Blob

Android
iOS
tvOS

bytes()

Retrieves byte content of the entire file.

Returns:

Uint8Array

The contents of the file as a Uint8Array.

Android
iOS
tvOS

copy(destination)

ParameterType
destinationDirectory | File

Copies a file.

Returns:

any

Android
iOS
tvOS

create(options)

ParameterType
options
(optional)
CreateOptions

Creates a file.

Returns:

void

Android
iOS
tvOS

delete()

Deletes a file.

Returns:

void

Android
iOS
tvOS

downloadFileAsync(url, destination)

ParameterTypeDescription
urlstring

The URL of the file to download.

destinationDirectory | 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.

Returns:

Promise<File>

A promise that resolves to the downloaded file.

Example

const file = await File.downloadFileAsync("https://example.com/image.png", new Directory(Paths.document));
Android
iOS
tvOS

move(destination)

ParameterType
destinationDirectory | File

Moves a directory. Updates the uri property that now points to the new location.

Returns:

any

Android
iOS
tvOS

open()

Returns a FileHandle object that can be used to read and write data to the file.

Returns:

FileHandle

Android
iOS
tvOS

text()

Retrieves text from the file.

Returns:

string

The contents of the file as string.

Android
iOS
tvOS

write(content)

ParameterTypeDescription
contentstring | Uint8Array

The content to write into the file.


Writes content to the file.

Returns:

void

Android
iOS
tvOS

Paths

Type: Class extends PathUtilities

Paths Properties

Android
iOS
tvOS

appleSharedContainers

Type: Record<string, Directory>
Android
iOS
tvOS

cache

Type: 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.

Android
iOS
tvOS

document

Type: Directory

A property containing the document directory – a place to store files that are safe from being deleted by the system.

Paths Methods

Android
iOS
tvOS

basename(path, ext)

ParameterTypeDescription
pathstring | File | Directory

The path to get the base name from.

ext
(optional)
string

An optional file extension.


Returns the base name of a path.

Returns:

string

A string representing the base name.

Android
iOS
tvOS

dirname(path)

ParameterTypeDescription
pathstring | File | Directory

The path to get the directory name from.


Returns the directory name of a path.

Returns:

string

A string representing the directory name.

Android
iOS
tvOS

extname(path)

ParameterTypeDescription
pathstring | File | Directory

The path to get the extension from.


Returns the extension of a path.

Returns:

string

A string representing the extension.

Android
iOS
tvOS

isAbsolute(path)

ParameterTypeDescription
pathstring | File | Directory

The path to check.


Checks if a path is absolute.

Returns:

boolean

true if the path is absolute, false otherwise.

Android
iOS
tvOS

join(...paths)

ParameterTypeDescription
...paths(string | File | Directory)[]

An array of path segments.


Joins path segments into a single path.

Returns:

string

A string representing the joined path.

Android
iOS
tvOS

normalize(path)

ParameterTypeDescription
pathstring | File | Directory

The path to normalize.


Normalizes a path.

Returns:

string

A string representing the normalized path.

Android
iOS
tvOS

parse(path)

ParameterTypeDescription
pathstring | File | Directory

The path to parse.


Parses a path into its components.

Returns:

{ base: string, dir: string, ext: string, name: string, root: string }

An object containing the parsed path components.

Android
iOS
tvOS

relative(from, to)

ParameterTypeDescription
fromstring | File | Directory

The base path.

tostring | File | Directory

The relative path.


Resolves a relative path to an absolute path.

Returns:

string

A string representing the resolved path.