README.md

expo-file-dl

A library which allows you to download files to an arbitrary folder on the mobile device while updating you on the download progress and displaying notifications to the user about the status of the file download. Downloading files to a folder in Expo isn't super-obvious so this library is meant to bridge the gap a bit. To use this library you need to be using expo-notifications (bare and managed workflow both supported) and need to have the following in your app:

1. An existing notification channel
2. A notification-handler function
3. CAMERA_ROLL permissions granted by the user

Demo-Preview

Table of contents

• Table of contents
• Installation
  • Managed Expo project
  • Bare Expo project or plain React-Native project
• Usage
  • downloadToFolder
• Development
• Contribute
  • Sponsor
    • Liberapay
    • PayPal
  • Adding new features or fixing bugs

Installation

(Back to top)

Managed Expo project

Just run

yarn add expo-file-dl

Bare Expo project or plain React-Native project

First, you need to install react-native-unimodules if you haven't already. Follow these instructions to do so.

Then, add android:requestLegacyExternalStorage="true" to your AndroidManifest.xml like so

<manifest ... >
  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

Then add this to your app.json file

{
  "expo": {
    ...
    "android": {
      ...
      "useNextNotificationsApi": true,
    }
  }
}

Finally, run

yarn add expo-file-dl

Usage

(Back to top)

To see a full-code working example, you can check out this example app: expo-file-dl-example

There is a bare branch which has a working app using the bare workflow in addition to the master branch which uses the managed workflow

To use the following functions, you need to have:

1. created a NotificationChannel using Notifications.setNotificationChannelAsync (docs)
2. set up a NotificationHandler using Notifications.setNotificationHandler (docs)
3. been granted CAMERA_ROLL permissions by the user, multiple ways to do this, one way is through Permissions.askAsync(Permissions.CAMERA_ROLL) (docs)

downloadToFolder

simplest invocation

import { downloadToFolder } from 'expo-file-dl';

...

      <Button title='Download' onPress={async () => {
        await downloadToFolder(uri, filename, folder, channelId);
      }}

with configuration options

import { downloadToFolder } from 'expo-file-dl';

...

      <Button title='Download' onPress={async () => {
        await downloadToFolder(
          uri,
          filename,
          folder,
          channelId,
          {
            notificationType: {notification: 'custom'},
            notificationContent: {
              downloading: {
                title: 'Download In Progress',
              },
              finished: {
                title: 'Complete!',
              },
              error: {
                title: 'Oops!'
              },
            },
            downloadProgressCallback: (data) => {
              const {totalBytesWritten, totalBytesExpectedToWrite} = data;
              const pctg = 100 * (totalBytesWritten / totalBytesExpectedToWrite);
              setProgressPercentage(`${pctg.toFixed(0)}%`);
            },
          }
        );
      }}

Arguments:

• uri: string - the URI of the resource you want to download, currently handles images, videos, and audio well, unsure about other types of resources
• filename: string - the filename to save the resource to (only the filename, no path information)
• folder: string - the name of the folder on the device to save the resource to, if the folder does not exist it will be created
• channelId: string - the id of the NotificationChannel you created earlier
• options: object - Optional argument. an object containing any (or none) of the following configurable options:
  • notificationType?: { notification: "managed" | "custom" | "none" } - Optional argument. The managed type uses set defaults for any and all notifications sent during file download. You can override these defaults with { notification: "custom" } and you can opt out of sending notifications altogether with { notification: "none" }
  • notificationContent?: { downloading: NotificationContentInput, finished: NotificationContentInput, error: NotificationContentInput } - Optional argument, only looked at if notificationType is set to { notification: "custom" } otherwise it is ignored. See the docs for NotificationContentInput to see what options are available to customize
  • downloadProgressCallback?: ({totalBytesWritten: number, totalBytesExpectedToWrite: number}) => void - Optional argument, gets called on every file write to the system with information about how much of the file has been written and how much is left to write.

This function will download a file from the given URI to a file in the folder with the given name (and will create a folder with the given name if none currently exists). This downloaded file will be visible from other apps, including multimedia apps and file managers. While the download is occurring the user will receive status notifications.

Please see expo-file-dl-example for a working example of this function in action

Development

(Back to top)

The recommended way to work on this app is the following:

Clone this repo and install dependencies

git clone https://github.com/kathawala/expo-file-dl.git
cd expo-file-dl
yarn install

Clone the expo-file-dl-example repo and install dependencies

git clone https://github.com/kathawala/expo-file-dl-example.git
cd expo-file-dl-example
yarn install

Change package.json in the expo-file-dl-example code to point to the local copy of expo-file-dl

package.json

{
    ...
    "dependencies": {
        ...
        "expo-file-dl": "../expo-file-dl",
        ...
    }
    ...
}

Now you can make changes to expo-file-dl. When you want to test them out, go to the expo-file-dl-example directory and start the expo server

(if you don't have expo run yarn add global expo-cli)

cd ../expo-file-dl-example
expo start

And you can test the changes on your phone or emulator

Contribute

Sponsor

(Back to top)

If this saved you development time or you otherwise found it useful, leave a star or follow in GitHub.

You can also buy me a coffee to say thanks:

Liberapay

PayPal

Adding new features or fixing bugs

(Back to top)

Follow the instructions above if you want to set up the environment to write a PR

Bug reports are also welcome, please provide a minimum reproducible example along with a bug report