FileSystem

Installation

Configuration

Example Usage

Downloading files

const callback = downloadProgress => {
  const progress = downloadProgress.totalBytesWritten / downloadProgress.totalBytesExpectedToWrite;
  this.setState({
    downloadProgress: progress,
  });
};

const downloadResumable = FileSystem.createDownloadResumable(
  'http://techslides.com/demos/sample-videos/small.mp4',
  FileSystem.documentDirectory + 'small.mp4',
  {},
  callback
);

try {
  const { uri } = await downloadResumable.downloadAsync();
  console.log('Finished downloading to ', uri);
} catch (e) {
  console.error(e);
}

try {
  await downloadResumable.pauseAsync();
  console.log('Paused download operation, saving for future retrieval');
  AsyncStorage.setItem('pausedDownload', JSON.stringify(downloadResumable.savable()));
} catch (e) {
  console.error(e);
}

try {
  const { uri } = await downloadResumable.resumeAsync();
  console.log('Finished downloading to ', uri);
} catch (e) {
  console.error(e);
}

//To resume a download across app restarts, assuming the the DownloadResumable.savable() object was stored:
const downloadSnapshotJson = await AsyncStorage.getItem('pausedDownload');
const downloadSnapshot = JSON.parse(downloadSnapshotJson);
const downloadResumable = new FileSystem.DownloadResumable(
  downloadSnapshot.url,
  downloadSnapshot.fileUri,
  downloadSnapshot.options,
  callback,
  downloadSnapshot.resumeData
);

try {
  const { uri } = await downloadResumable.resumeAsync();
  console.log('Finished downloading to ', uri);
} catch (e) {
  console.error(e);
}

Managing Giphy's

import * as FileSystem from 'expo-file-system';

const gifDir = FileSystem.cacheDirectory + 'giphy/';
const gifFileUri = (gifId: string) => gifDir + `gif_${gifId}_200.gif`;
const gifUrl = (gifId: string) => `https://media1.giphy.com/media/${gifId}/200.gif`;

// Checks if gif directory exists. If not, creates it
async function ensureDirExists() {
  const dirInfo = await FileSystem.getInfoAsync(gifDir)
  if (!dirInfo.exists) {
    console.log('Gif directory doesn\'t exist, creating...');
    await FileSystem.makeDirectoryAsync(gifDir, { intermediates: true });
  }
}

// Downloads all gifs specified as array of IDs 
export async function addMultipleGifs(gifIds: string[]) {
  try {
    await ensureDirExists();

    console.log('Downloading', gifIds.length, 'gif files...');
    await Promise.all(gifIds.map(id => FileSystem.downloadAsync(gifUrl(id), gifFileUri(id))));
  } catch(e) {
    console.error("Couldn't download gif files:", e);
  }
}

// Returns URI to our local gif file
// If our gif doesn't exist locally, it downloads it
export async function getSingleGif(gifId: string) {
  await ensureDirExists();
  
  const fileUri = gifFileUri(gifId);
  const fileInfo = await FileSystem.getInfoAsync(fileUri);

  if (!fileInfo.exists) {
    console.log("Gif isn't cached locally. Downloading...");
    await FileSystem.downloadAsync(gifUrl(gifId), fileUri);
  }

  return fileUri;
}

// Exports shareable URI - it can be shared outside your app
export async function getGifContentUri(gifId: string) {
  return FileSystem.getContentUriAsync(await getSingleGif(gifId));
}

// Deletes whole giphy directory with all its content
export async function deleteAllGifs() {
  console.log('Deleting all GIF files...');
  await FileSystem.deleteAsync(gifDir);
}

API

import * as FileSystem from 'expo-file-system';

Supported URI schemes

Directories

FileSystem.documentDirectory

FileSystem.cacheDirectory

Constants

FileSystem.EncodingType

• FileSystem.EncodingType.UTF8 -- Standard readable format.
• FileSystem.EncodingType.Base64 -- Binary, radix-64 representation.

FileSystem.FileSystemSessionType

• FileSystem.FileSystemSessionType.BACKGROUND -- Using this mode means that the downloading/uploading session on the native side will work even if the application is moved to background. If the task completes while the application is in background, the Promise will be either resolved immediately or (if the application execution has already been stopped) once the app is moved to foreground again.

  Note: The background session doesn't fail if the server or your connection is down. Rather, it continues retrying until the task succeeds or is canceled manually.

• FileSystem.FileSystemSessionType.FOREGROUND -- Using this mode means that downloading/uploading session on the native side will be terminated once the application becomes inactive (e.g. when it goes to background). Bringing the application to foreground again would trigger Promise rejection.

FileSystem.FileSystemUploadOptions

• FileSystem.FileSystemUploadOptions.BINARY_CONTENT -- The file will be sent as a request's body. The request can't contain additional data.
• FileSystem.FileSystemUploadOptions.MULTIPART -- An RFC 2387-compliant request body. The provided file will be encoded into HTTP request. This request can contain additional data.

How to handle such requests?

const express = require('express');
const app = express();
const fs = require('fs');
const multer = require('multer');
const upload = multer({ dest: 'uploads/' });

// This method will save the binary content of the request as a file.
app.patch('/binary-upload', (req, res) => {
  req.pipe(fs.createWriteStream('./uploads/image' + Date.now() + '.png'));
  res.end('OK');
});

// This method will save a "photo" field from the request as a file.
app.patch('/multipart-upload', upload.single('photo'), (req, res) => {
  // You can access other HTTP parameters. They are located in the body object.
  console.log(req.body);
  res.end('OK');
});

app.listen(3000, () => {
  console.log('Working on port 3000');
});

Methods

FileSystem.getInfoAsync(fileUri, options)

Arguments

• fileUri (string) -- URI to the file or directory. It may be e.g. URI returned by CameraRoll.getPhotos(). See supported URI schemes.
• options (object) -- A map of options:
  • md5 (boolean) -- Whether to return the MD5 hash of the file. false by default.
  • size (boolean) -- Whether to include the size of the file if operating on a source from CameraRoll.getPhotos() (skipping this can prevent downloading the file if it's stored in iCloud, for example). The size is always returned for file:// locations.

Returns

• exists (boolean) -- true.
• isDirectory (boolean) -- true if this is a directory, false if it is a file
• modificationTime (number) -- The last modification time of the file expressed in seconds since epoch.
• size (number) -- The size of the file in bytes. If operating on a source from CameraRoll.getPhotos(), only present if the size option was truthy.
• uri (string) -- A file:// URI pointing to the file. This is the same as the fileUri input parameter.
• md5 (string) -- Present if the md5 option was truthy. Contains the MD5 hash of the file.

FileSystem.readAsStringAsync(fileUri, options)

Arguments

• fileUri (string) -- file:// URI to the file or directory.
• options (object) -- Optional props that define how a file must be read.
  • encoding (EncodingType) -- The encoding format to use when reading the file. Options: FileSystem.EncodingType.UTF8, FileSystem.EncodingType.Base64. Default is FileSystem.EncodingType.UTF8.
  • length (number) -- Optional number of bytes to read. This option is only used when encoding: FileSystem.EncodingType.Base64 and position is defined.
  • position (number) -- Optional number of bytes to skip. This option is only used when encoding: FileSystem.EncodingType.Base64 and length is defined.

Returns

FileSystem.writeAsStringAsync(fileUri, contents, options)

Arguments

• fileUri (string) -- file:// URI to the file or directory.
• contents (string) -- The string to replace the contents of the file with.
• options (object) -- Optional props that define how a file must be written.
  • encoding (string) -- The encoding format to use when writing the file. Options: FileSystem.EncodingType.UTF8, FileSystem.EncodingType.Base64. Default is FileSystem.EncodingType.UTF8

FileSystem.deleteAsync(fileUri, options)

Arguments

• fileUri (string) -- file:// URI to the file or directory.
• options (object) -- A map of options:
  • idempotent (boolean) -- If true, don't throw an error if there is no file or directory at this URI. false by default.

FileSystem.moveAsync(options)

Arguments

• options (object) -- A map of options:
  • from (string) -- file:// URI to the file or directory at its original location.
  • to (string) -- file:// URI to the file or directory at what should be its new location.

FileSystem.copyAsync(options)

Arguments

• options (object) -- A map of options:
  • from (string) -- URI to the asset, file or directory to copy. It can be e.g. URI returned by CameraRoll.getPhotos(). See supported URI schemes.
  • to (string) -- The file:// URI to the new copy to create.

FileSystem.makeDirectoryAsync(fileUri, options)

Arguments

• fileUri (string) -- file:// URI to the new directory to create.
• options (object) -- A map of options:
  • intermediates (boolean) -- If true, create any non-existent parent directories when creating the directory at fileUri. If false, raises an error if any of the intermediate parent directories does not exist or if the child directory already exists. false by default.

FileSystem.readDirectoryAsync(fileUri)

Arguments

• fileUri (string) -- file:// URI to the directory.

Returns

FileSystem.downloadAsync(uri, fileUri, options)

Example

FileSystem.downloadAsync(
  'http://techslides.com/demos/sample-videos/small.mp4',
  FileSystem.documentDirectory + 'small.mp4'
)
  .then(({ uri }) => {
    console.log('Finished downloading to ', uri);
  })
  .catch(error => {
    console.error(error);
  });

Arguments

• url (string) -- The remote URI to download from.
• fileUri (string) -- The local URI of the file to download to. If there is no file at this URI, a new one is created. If there is a file at this URI, its contents are replaced. The directory for the file must exist.
• options (object) -- A map of options:
  • headers (object) -- An object containing all the HTTP header fields and their values for the download network request. The keys and values of the object are the header names and values respectively.
  • md5 (boolean) -- If true, include the MD5 hash of the file in the returned object. false by default. Provided for convenience since it is common to check the integrity of a file immediately after downloading.
  • sessionType (FileSystemSessionType) -- (iOS only) A session type. Determines if tasks can be handled in the background. On Android, sessions always work in the background and you can't change it. Defaults to FileSystemSessionType.BACKGROUND.

Returns

• uri (string) -- A file:// URI pointing to the file. This is the same as the fileUri input parameter.
• status (number) -- The HTTP response status code for the download network request.
• headers (object) -- An object containing all the HTTP response header fields and their values for the download network request. The keys and values of the object are the header names and values respectively.
• md5 (string) -- Present if the md5 option was truthy. Contains the MD5 hash of the file.

FileSystem.uploadAsync(url, fileUri, options)

Arguments

• url (string) -- The remote URL, where the file will be sent.
• fileUri (string) -- The local URI of the file to send. The file must exist.
• options (object) -- A map of options:
  • headers (object) -- An object containing all the HTTP header fields and their values for the upload network request. The keys and values of the object are the header names and values respectively.
  • httpMethod (String) -- The request method. Accepts values: 'POST', 'PUT', 'PATCH. Default to 'POST'.
  • sessionType (FileSystemSessionType) -- (iOS only) A session type. Determines if tasks can be handled in the background. On Android, sessions always work in the background and you can't change it. Defaults to FileSystemSessionType.BACKGROUND.
  • uploadType (FileSystemUploadOptions) -- Upload type determines how the file will be sent to the server. Default to FileSystemUploadType.BINARY_CONTENT.
  If uploadType is equal FileSystemUploadType.MULTIPART, more options are available:
  • fieldName (string) -- The name of the field which will hold uploaded file. Defaults to the file name without an extension.
  • mimeType (string) -- The MIME type of the provided file. If not provided, the module will try to guess it based on the extension.
  • parameters (Record<string, string>) -- Additional form properties. They will be located in the request body.

Returns

• status (number) -- The HTTP response status code for the upload network request.
• headers (object) -- An object containing all the HTTP response header fields and their values for the upload network request. The keys and values of the object are the header names and values respectively.
• body (string) -- The body of the server response.

FileSystem.createDownloadResumable(uri, fileUri, options, callback, resumeData)

Arguments

• url (string) -- The remote URI to download from.
• fileUri (string) -- The local URI of the file to download to. If there is no file at this URI, a new one is created. If there is a file at this URI, its contents are replaced. The directory for the file must exist.
• options (object) -- A map of options:
  • md5 (boolean) -- If true, include the MD5 hash of the file in the returned object. false by default. Provided for convenience since it is common to check the integrity of a file immediately after downloading.
  • headers (object) -- An object containing any additional HTTP header fields required for the request. The keys and values of the object are the header names and values respectively.
• callback (function) -- This function is called on each data write to update the download progress. An object with the following fields are passed:
  • totalBytesWritten (number) -- The total bytes written by the download operation.
  • totalBytesExpectedToWrite (number) -- The total bytes expected to be written by the download operation. A value of -1 means that the server did not return the Content-Length header and the total size is unknown. Without this header, you won't be able to track the download progress.

  Note: When the app has been moved to the background, this callback won't be fired until it's moved to the foreground.

• resumeData (string) -- The string which allows the api to resume a paused download. This is set on the DownloadResumable object automatically when a download is paused. When initializing a new DownloadResumable this should be null.

FileSystem.DownloadResumable.downloadAsync()

Returns

• uri (string) -- A file:// URI pointing to the file. This is the same as the fileUri input parameter.
• status (number) -- The HTTP status code for the download network request.
• headers (object) -- An object containing all the HTTP header fields and their values for the download network request. The keys and values of the object are the header names and values respectively.
• md5 (string) -- Present if the md5 option was truthy. Contains the MD5 hash of the file.

FileSystem.DownloadResumable.pauseAsync()

Returns

• url (string) -- The remote URI to download from.
• fileUri (string) -- The local URI of the file to download to. If there is no file at this URI, a new one is created. If there is a file at this URI, its contents are replaced.
• options (object) -- A map of options:
  • md5 (boolean) -- If true, include the MD5 hash of the file in the returned object. false by default. Provided for convenience since it is common to check the integrity of a file immediately after downloading.
• resumeData (string) -- The string which allows the API to resume a paused download.

FileSystem.DownloadResumable.resumeAsync()

Returns

• uri (string) -- A file:// URI pointing to the file. This is the same as the fileUri input parameter.
• status (number) -- The HTTP status code for the download network request.
• headers (object) -- An object containing all the HTTP header fields and their values for the download network request. The keys and values of the object are the header names and values respectively.
• md5 (string) -- Present if the md5 option was truthy. Contains the MD5 hash of the file.

FileSystem.DownloadResumable.savable()

Returns

• url (string) -- The remote URI to download from.
• fileUri (string) -- The local URI of the file to download to. If there is no file at this URI, a new one is created. If there is a file at this URI, its contents are replaced.
• options (object) -- A map of options:
  • md5 (boolean) -- If true, include the MD5 hash of the file in the returned object. false by default. Provided for convenience since it is common to check the integrity of a file immediately after downloading.
• resumeData (string) -- The string which allows the api to resume a paused download.

FileSystem.getContentUriAsync(fileUri)

Example

FileSystem.getContentUriAsync(uri).then(cUri => {
  console.log(cUri);
  IntentLauncher.startActivityAsync('android.intent.action.VIEW', {
    data: cUri,
    flags: 1,
  });
});

Arguments

• fileUri (string) -- The local URI of the file. If there is no file at this URI, an exception will be thrown.

Returns

FileSystem.getFreeDiskStorageAsync()

Example

FileSystem.getFreeDiskStorageAsync().then(freeDiskStorage => {
  // Android: 17179869184
  // iOS: 17179869184
});

Returns

FileSystem.getTotalDiskCapacityAsync()

Example

FileSystem.getTotalDiskCapacityAsync().then(totalDiskCapacity => {
  // Android: 17179869184
  // iOS: 17179869184
});

Returns

Supported URI schemes