Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kathawala/expo-file-dl
Download files to any folder and notify the user while the download is happening and when the download finishes
https://github.com/kathawala/expo-file-dl
expo expo-file-download expo-notifications expo-sdk file-download package react-native react-native-file-download typescript
Last synced: 3 months ago
JSON representation
Download files to any folder and notify the user while the download is happening and when the download finishes
- Host: GitHub
- URL: https://github.com/kathawala/expo-file-dl
- Owner: kathawala
- License: mit
- Created: 2020-11-07T09:05:46.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-04-06T21:47:59.000Z (almost 3 years ago)
- Last Synced: 2024-04-27T01:03:50.126Z (10 months ago)
- Topics: expo, expo-file-download, expo-notifications, expo-sdk, file-download, package, react-native, react-native-file-download, typescript
- Language: TypeScript
- Homepage:
- Size: 746 KB
- Stars: 44
- Watchers: 3
- Forks: 8
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](#table-of-contents)
- [Installation](#installation)
- [Managed Expo project](#managed-expo-project)
- [Bare Expo project or plain React-Native project](#bare-expo-project-or-plain-react-native-project)
- [Usage](#usage)
- [downloadToFolder](#downloadtofolder)
- [Development](#development)
- [Contribute](#contribute)
- [Sponsor](#sponsor)
- [Liberapay](#liberapay)
- [PayPal](#paypal)
- [Adding new features or fixing bugs](#adding-new-features-or-fixing-bugs)
# Installation
[(Back to top)](#table-of-contents)
## 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](https://docs.expo.io/bare/installing-unimodules/) to do so.
Then, add `android:requestLegacyExternalStorage="true"` to your `AndroidManifest.xml` like so
```xml
...
```
Then add this to your `app.json` file
```
{
"expo": {
...
"android": {
...
"useNextNotificationsApi": true,
}
}
}
```
Finally, run
```
yarn add expo-file-dl
```
# Usage
[(Back to top)](#table-of-contents)
To see a full-code working example, you can check out this example app: [expo-file-dl-example](https://github.com/kathawala/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](https://docs.expo.io/versions/v39.0.0/sdk/notifications/#setnotificationchannelasyncidentifier-string-channel-notificationchannelinput-promisenotificationchannel--null))
2. set up a `NotificationHandler` using `Notifications.setNotificationHandler` ([docs](https://docs.expo.io/versions/v39.0.0/sdk/notifications/#setnotificationchannelasyncidentifier-string-channel-notificationchannelinput-promisenotificationchannel--null))
3. been granted `CAMERA_ROLL` permissions by the user, multiple ways to do this, one way is through `Permissions.askAsync(Permissions.CAMERA_ROLL)` ([docs](https://docs.expo.io/versions/v39.0.0/sdk/permissions/#permissionsaskasynctypes))
## downloadToFolder
simplest invocation
```jsx
import { downloadToFolder } from 'expo-file-dl';
...
{
await downloadToFolder(uri, filename, folder, channelId);
}}
```
with configuration options
```jsx
import { downloadToFolder } from 'expo-file-dl';
...
{
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](https://docs.expo.io/versions/v39.0.0/sdk/notifications/#notificationcontentinput) 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](https://github.com/kathawala/expo-file-dl-example) for a working example of this function in action
# Development
[(Back to top)](#table-of-contents)
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)](#table-of-contents)
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
[](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=LHG78XBMVTU82&item_name=open+source+software¤cy_code=USD)
### Adding new features or fixing bugs
[(Back to top)](#table-of-contents)
Follow the [instructions above](#development) 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