Source: https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next

Hide navigation

Search

Ctrl K

Home Guides EAS Reference Learn

Reference version

SDK 53

Archive Expo Snack Discord and Forums Newsletter

Expo FileSystem (next)

GitHub Changelog npm

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

GitHub Changelog npm

Android

iOS

tvOS

Bundled version:

~18.1.11

Copy page

---

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.

To provide quicker updates, expo-file-system/next is currently unsupported in Expo Go and Snack. To use it, create a development build .

expo-file-system/next provides access to the file system stored locally on the device. It can also download files from the network.

Installation

---

Terminal

Copy

- 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

---

Writing and reading text files

example.ts

Copy

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

Using downloadFileAsync:

example.ts

Copy

import { Directory, 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); }

Or using expo/fetch:

example.ts

Copy

import { fetch } from 'expo/fetch'; import { File, Paths } from 'expo-file-system/next'; 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:

example.ts

Copy

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 response = await fetch('https://example.com', { method: 'POST', body: file, });

Or using the FormData constructor:

example.ts

Copy

import { fetch } from 'expo/fetch'; import { File, Paths } from 'expo-file-system/next'; const src = 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

example.ts

Copy

import { Directory, 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' const copiedFile = new File(Paths.cache, 'example-copy.txt'); file.copy(copiedFile); console.log(copiedFile.uri); // '${cacheDirectory}/example-copy.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

Copy

import * as 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

Copy

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); }

Show More

API

---

Classes

---

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

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.

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.

name

Type: string

Directory name.

parentDirectory

Type: [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory)

Directory containing the file.

Directory Methods

copy(destination)

| Parameter | Type | | --- | --- | | destination | [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) |

Copies a directory.

Returns:

void

create(options)

| Parameter | Type | | --- | --- | | options(optional) | [CreateOptions](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#createoptions) |

Creates a directory that the current uri points to.

Returns:

void

delete()

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

Returns:

void

list()

Lists the contents of a directory. Calling this method if the parent directory does not exist will throw an error.

Returns:

([File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) | [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) )[]

An array of Directory and File instances.

move(destination)

| Parameter | Type | | --- | --- | | destination | [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) |

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

Returns:

void

File

Type: Class extends FileSystemFile

File Properties

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.

md5

Literal type: union

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

Acceptable values are: null | string

size

Literal type: union

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

Acceptable values are: null | number

type

Literal type: union

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

Acceptable values are: null | string

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.

extension

Type: string

File extension.

Example

'.png'

name

Type: string

File name. Includes the extension.

parentDirectory

Type: [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory)

Directory containing the file.

File Methods

base64()

Retrieves content of the file as base64.

Returns:

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.

Returns:

[Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)

bytes()

Retrieves byte content of the entire file.

Returns:

[Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)

The contents of the file as a Uint8Array.

copy(destination)

| Parameter | Type | | --- | --- | | destination | [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) |

Copies a file.

Returns:

void

create(options)

| Parameter | Type | | --- | --- | | options(optional) | [CreateOptions](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#createoptions) |

Creates a file.

Returns:

void

delete()

Deletes a file.

Returns:

void

downloadFileAsync(url, destination)

| Parameter | Type | Description | | --- | --- | --- | | url | string | The URL of the file to download. | | destination | [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) <[File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) >

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)

| Parameter | Type | | --- | --- | | destination | [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) |

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

Returns:

void

open()

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

Returns:

[FileHandle](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#filehandle)

readableStream()

Returns:

[ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) <[Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) >

text()

Retrieves text from the file.

Returns:

string

The contents of the file as string.

writableStream()

Returns:

[WritableStream](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) <[Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) >

write(content)

| Parameter | Type | Description | | --- | --- | --- | | content | string \| [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | The content to write into the file. |

Writes content to the file.

Returns:

void

FileHandle

FileHandle Properties

offset

Literal type: 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

size

Literal type: union

A size of the file in bytes or null if the file handle is closed.

Acceptable values are: null | number

FileHandle Methods

close()

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.

Returns:

void

readBytes(length)

| Parameter | Type | Description | | --- | --- | --- | | length | number | The number of bytes to read. |

Reads the specified amount of bytes from the file at the current offset.

Returns:

[Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)

writeBytes(bytes)

| Parameter | Type | Description | | --- | --- | --- | | bytes | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | A Uint8Array array containing bytes to write. |

Writes the specified bytes to the file at the current offset.

Returns:

void

Paths

Type: Class extends PathUtilities

Paths Properties

appleSharedContainers

Type: Record<string, [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) >

cache

Type: [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#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.

document

Type: [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory)

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

Paths Methods

basename(path, ext)

| Parameter | Type | Description | | --- | --- | --- | | path | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#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.

dirname(path)

| Parameter | Type | Description | | --- | --- | --- | | path | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) | The path to get the directory name from. |

Returns the directory name of a path.

Returns:

string

A string representing the directory name.

extname(path)

| Parameter | Type | Description | | --- | --- | --- | | path | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) | The path to get the extension from. |

Returns the extension of a path.

Returns:

string

A string representing the extension.

isAbsolute(path)

| Parameter | Type | Description | | --- | --- | --- | | path | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) | The path to check. |

Checks if a path is absolute.

Returns:

boolean

true if the path is absolute, false otherwise.

join(...paths)

| Parameter | Type | Description | | --- | --- | --- | | ...paths | (string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) )[] | An array of path segments. |

Joins path segments into a single path.

Returns:

string

A string representing the joined path.

normalize(path)

| Parameter | Type | Description | | --- | --- | --- | | path | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) | The path to normalize. |

Normalizes a path.

Returns:

string

A string representing the normalized path.

parse(path)

| Parameter | Type | Description | | --- | --- | --- | | path | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#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.

relative(from, to)

| Parameter | Type | Description | | --- | --- | --- | | from | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) | The base path. | | to | string \| [File](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#file) \| [Directory](https://docs.expo.dev/versions/v53.0.0/sdk/filesystem-next#directory) | The relative path. |

Resolves a relative path to an absolute path.

Returns:

string

A string representing the resolved path.

Types

---

CreateOptions

| Property | Type | Description | | --- | --- | --- | | intermediates(optional) | boolean | Whether to create intermediate directories if they do not exist.<br><br>Default:false | | overwrite(optional) | boolean | Whether to overwrite the file or directory if it exists.<br><br>Default:false |