Repository files navigation

This repository no longer is the main location of "react-native-fetch-blob".

The owners of this fork have agreed to maintain this package:

https://github.com/joltup/rn-fetch-blob

That means issues and PRs should be posted there.

A project committed to making file access and data transfer easier and more efficient for React Native developers.

For Firebase Storage solution, please upgrade to the latest version for the best compatibility.

• Transfer data directly from/to storage without BASE64 bridging
• File API supports regular files, Asset files, and CameraRoll files
• Native-to-native file manipulation API, reduce JS bridging performance loss
• File stream support for dealing with large file
• Blob, File, XMLHttpRequest polyfills that make browser-based library available in RN (experimental)
• JSON stream supported base onOboe.js @jimhigson

• About
• Installation
• HTTP Data Transfer
• Regular Request
• Download file
• Upload file
• Multipart/form upload
• Upload/Download progress
• Cancel HTTP request
• Android Media Scanner, and Download Manager Support
• Self-Signed SSL Server
• Transfer Encoding
• Drop-in Fetch Replacement
• File System
• File access
• File stream
• Manage cached files
• Web API Polyfills
• Performance Tips
• API References
• Caveats
• Development

This project was started in the cause of solving issuefacebook/react-native#854, React Native's lacks ofBlob implementation which results into problems when transferring binary data.

It is committed to making file access and transfer easier and more efficient for React Native developers. We've implemented highly customizable filesystem and network module which plays well together. For example, developers can upload and download data directly from/to storage, which is more efficient, especially for large files. The file system supports file stream, so you don't have to worry about OOM problem when accessing large files.

In0.8.0 we introduced experimental Web API polyfills that make it possible to use browser-based libraries in React Native, such as,FireBase JS SDK

Install package from npm

npm install --save react-native-fetch-blob

Or if using CocoaPods, add the pod to yourPodfile

pod 'react-native-fetch-blob',    :path => '../node_modules/react-native-fetch-blob'

After0.10.3 you can install this package directly from Github

# replace <branch_name> with any one of the branchesnpm install --save github:wkh237/react-native-fetch-blob-package#<branch_name>

Automatically Link Native Modules

For 0.29.2+ projects, simply link native packages via the following command (note: rnpm has been merged into react-native)

react-native link

As for projects < 0.29 you needrnpm to link native packages

rnpm link

Optionally, use the following command to add Android permissions toAndroidManifest.xml automatically

RNFB_ANDROID_PERMISSIONS=true react-native link

pre 0.29 projects

RNFB_ANDROID_PERMISSIONS=true rnpm link

The link script might not take effect if you have non-default project structure, please visitthe wiki to link the package manually.

Grant Permission to External storage for Android 5.0 or lower

The mechanism for granting Android permissions has slightly different since Android 6.0 released, please refer toOfficial Document.

If you're going to access external storage (say, SD card storage) forAndroid 5.0 (or lower) devices, you might have to add the following line toAndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"    package="com.rnfetchblobtest"    android:versionCode="1"    android:versionName="1.0">    <uses-permission android:name="android.permission.INTERNET" />    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>+   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />+   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />    ...

Also, if you're going to useAndroid Download Manager you have to add this toAndroidManifest.xml

    <intent-filter>            <action android:name="android.intent.action.MAIN" />            <category android:name="android.intent.category.LAUNCHER" />+           <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>    </intent-filter>

Grant Access Permission for Android 6.0

Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions inAndroidManifest.xml won't work for Android 6.0+ devices. To grant permissions in runtime, you might usePermissionAndroid API.

ES6

The module uses ES6 style export statement, simply useimport to load the module.

importRNFetchBlobfrom'react-native-fetch-blob'

ES5

If you're using ES5 require statement to load the module, please adddefault. Seehere for more detail.

var RNFetchBlob = require('react-native-fetch-blob').default

After0.8.0 react-native-fetch-blob automatically decides how to send the body by checking its type andContent-Type in the header. The rule is described in the following diagram

To sum up:

• To send a form data, theContent-Type header does not matter. When the body is anArray we will set proper content type for you.
• To send binary data, you have two choices, use BASE64 encoded string or path points to a file contains the body.
• If theContent-Type containing substring;BASE64 orapplication/octet the given body will be considered as a BASE64 encoded data which will be decoded to binary data as the request body.
• Otherwise, if a string starts withRNFetchBlob-file:// (which can simply be done byRNFetchBlob.wrap(PATH_TO_THE_FILE)), it will try to find the data from the URI string afterRNFetchBlob-file:// and use it as the request body.
• To send the body as-is, simply use aContent-Type header not containing;BASE64 orapplication/octet.

It is Worth to mentioning that the HTTP request uses cache by default, if you're going to disable it simply add a Cache-Control header'Cache-Control' : 'no-store'

After 0.9.4, we disabledChunked transfer encoding by default, if you're going to use it, you should explicitly set headerTransfer-Encoding toChunked.

Most simple way is download to memory and stored as BASE64 encoded string, this is handy when the response data is small.

// send http request in a new thread (using native code)RNFetchBlob.fetch('GET','http://www.example.com/images/img1.png',{Authorization :'Bearer access-token...',// more headers  ..})// when response status code is 200.then((res)=>{// the conversion is done in native codeletbase64Str=res.base64()// the following conversions are done in js, it's SYNClettext=res.text()letjson=res.json()})// Status code is not 200.catch((errorMessage,statusCode)=>{// error handling})

If the response data is large, that would be a bad idea to convert it into BASE64 string. A better solution is streaming the response directly into a file, simply add afileCache option to config, and set it totrue. This will make incoming response data stored in a temporary pathwithout any file extension.

These files won't be removed automatically, please refer toCache File Management

RNFetchBlob.config({// add this option that makes response data to be stored as a file,// this is much more performant.fileCache :true,}).fetch('GET','http://www.example.com/file/example.zip',{//some headers ..}).then((res)=>{// the temp file pathconsole.log('The file saved to ',res.path())})

Set Temp File Extension

Sometimes you might need a file extension for some reason. For example, when using file path as the source ofImage component, the path should end with something like .png or .jpg, you can do this by addappendExt option toconfig.

RNFetchBlob.config({fileCache :true,// by adding this option, the temp files will have a file extensionappendExt :'png'}).fetch('GET','http://www.example.com/file/example.zip',{//some headers ..}).then((res)=>{// the temp file path with file extension `png`console.log('The file saved to ',res.path())// Beware that when using a file path as Image source on Android,// you must prepend "file://"" before the file pathimageView=<Imagesource={{uri :Platform.OS==='android' ?'file://'+res.path()  :''+res.path()}}/>})

Use Specific File Path

If you prefer a particular file path rather than randomly generated one, you can usepath option. We've addedseveral constants in v0.5.0 which represents commonly used directories.

letdirs=RNFetchBlob.fs.dirsRNFetchBlob.config({// response data will be saved to this path if it has access right.path :dirs.DocumentDir+'/path-to-file.anything'}).fetch('GET','http://www.example.com/file/example.zip',{//some headers ..}).then((res)=>{// the path should be dirs.DocumentDir + 'path-to-file.anything'console.log('The file saved to ',res.path())})

These files won't be removed automatically, please refer toCache File Management

react-native-fetch-blob will convert the base64 string inbody to binary format using native API, this process is done in a separated thread so that it won't block your GUI.

RNFetchBlob.fetch('POST','https://content.dropboxapi.com/2/files/upload',{Authorization :"Bearer access-token...",'Dropbox-API-Arg':JSON.stringify({path :'/img-from-react-native.png',mode :'add',autorename :true,mute :false}),'Content-Type' :'application/octet-stream',// here's the body you're going to send, should be a BASE64 encoded string// (you can use "base64"(refer to the library 'mathiasbynens/base64') APIs to make one).// The data will be converted to "byte array"(say, blob) before request sent.},base64ImageString).then((res)=>{console.log(res.text())}).catch((err)=>{// error handling ..})

If you're going to use afile as request body, just wrap the path withwrap API.

RNFetchBlob.fetch('POST','https://content.dropboxapi.com/2/files/upload',{// dropbox upload headersAuthorization :"Bearer access-token...",'Dropbox-API-Arg':JSON.stringify({path :'/img-from-react-native.png',mode :'add',autorename :true,mute :false}),'Content-Type' :'application/octet-stream',// Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://`.// Or simply wrap the file path with RNFetchBlob.wrap().},RNFetchBlob.wrap(PATH_TO_THE_FILE)).then((res)=>{console.log(res.text())}).catch((err)=>{// error handling ..})

Inversion >= 0.3.0 you can also post files with form data, just put an array inbody, with elements have propertyname,data, andfilename(optional).

Elements have propertyfilename will be transformed into binary format, otherwise, it turns into utf8 string.

RNFetchBlob.fetch('POST','http://www.example.com/upload-form',{Authorization :"Bearer access-token",otherHeader :"foo",'Content-Type' :'multipart/form-data',},[// element with property `filename` will be transformed into `file` in form data{name :'avatar',filename :'avatar.png',data:binaryDataInBase64},// custom content type{name :'avatar-png',filename :'avatar-png.png',type:'image/png',data:binaryDataInBase64},// part file from storage{name :'avatar-foo',filename :'avatar-foo.png',type:'image/foo',data:RNFetchBlob.wrap(path_to_a_file)},// elements without property `filename` will be sent as plain text{name :'name',data :'user'},{name :'info',data :JSON.stringify({mail :'example@example.com',tel :'12345678'})},]).then((resp)=>{// ...}).catch((err)=>{// ...})

What if you want to append a file to form data? Just likeupload a file from storage example, wrapdata bywrap API (this feature is only available forversion >= v0.5.0). On version >=0.6.2, it is possible to set custom MIME type when appending a file to form data. But keep in mind when the file is large it's likely to crash your app. Please consider use other strategy (see#94).

RNFetchBlob.fetch('POST','http://www.example.com/upload-form',{Authorization :"Bearer access-token",otherHeader :"foo",// this is required, otherwise it won't be process as a multipart/form-data request'Content-Type' :'multipart/form-data',},[// append field data from file path{name :'avatar',filename :'avatar.png',// Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://`.// Or simply wrap the file path with RNFetchBlob.wrap().data:RNFetchBlob.wrap(PATH_TO_THE_FILE)},{name :'ringtone',filename :'ring.mp3',// use custom MIME typetype :'application/mp3',// upload a file from asset is also possible in version >= 0.6.2data :RNFetchBlob.wrap(RNFetchBlob.fs.asset('default-ringtone.mp3'))}// elements without property `filename` will be sent as plain text{name :'name',data :'user'},{name :'info',data :JSON.stringify({mail :'example@example.com',tel :'12345678'})},]).then((resp)=>{// ...}).catch((err)=>{// ...})

Inversion >= 0.4.2 it is possible to know the upload/download progress. After0.7.0 IOS and Android upload progress are also supported.

RNFetchBlob.fetch('POST','http://www.example.com/upload',{//... some headers,'Content-Type' :'octet-stream'},base64DataString)// listen to upload progress event.uploadProgress((written,total)=>{console.log('uploaded',written/total)})// listen to download progress event.progress((received,total)=>{console.log('progress',received/total)}).then((resp)=>{// ...}).catch((err)=>{// ...})

In0.9.6, you can specify an object as the first argument which containscount andinterval, to the frequency of progress event (this will be done in the native context a reduce RCT bridge overhead). Notice thatcount argument will not work if the server does not provide response content length.

RNFetchBlob.fetch('POST','http://www.example.com/upload',{//... some headers,'Content-Type' :'octet-stream'},base64DataString)// listen to upload progress event, emit every 250ms.uploadProgress({interval :250},(written,total)=>{console.log('uploaded',written/total)})// listen to download progress event, every 10%.progress({count :10},(received,total)=>{console.log('progress',received/total)}).then((resp)=>{// ...}).catch((err)=>{// ...})

After0.7.0 it is possible to cancel an HTTP request. Upon cancellation, it throws a promise rejection, be sure to catch it.

lettask=RNFetchBlob.fetch('GET','http://example.com/file/1')task.then(()=>{ ...})// handle request cancelled rejection.catch((err)=>{console.log(err)})// cancel the request, the callback function is optionaltask.cancel((err)=>{ ...})

0.9.0

If you have existing code that useswhatwg-fetch(the officialfetch), it's not necessary to replace them withRNFetchblob.fetch, you can simply use ourFetch Replacement. The difference between Official them is official fetch useswhatwg-fetch which wraps XMLHttpRequest polyfill under the hood. It's a great library for web developers, but does not play very well with RN. Our implementation is simply a wrapper of ourfetch andfs APIs, so you can access all the features we provided.

See document and examples

If you want to make a file inExternal Storage becomes visible in Picture, Downloads, or other built-in apps, you will have to useMedia Scanner orDownload Manager.

Media Scanner

Media scanner scans the file and categorizes by given MIME type, if MIME type not specified, it will try to resolve the file using its file extension.

RNFetchBlob.config({// DCIMDir is in external storagepath :dirs.DCIMDir+'/music.mp3'}).fetch('GET','http://example.com/music.mp3').then((res)=>RNFetchBlob.fs.scanFile([{path :res.path(),mime :'audio/mpeg'}])).then(()=>{// scan file success}).catch((err)=>{// scan file error})

Download Manager

When downloading large files on Android it is recommended to useDownload Manager, it supports a lot of native features like the progress bar, and notification, also the download task will be handled by OS, and more efficient.

When using DownloadManager,fileCache andpath properties inconfig will not take effect, because Android DownloadManager can only store files to external storage, also notice that Download Manager can only supportGET method, which means the request body will be ignored.

When download complete, DownloadManager will generate a file path so that you can deal with it.

RNFetchBlob.config({addAndroidDownloads :{useDownloadManager :true,// <-- this is the only thing required// Optional, override notification setting (default to true)notification :false,// Optional, but recommended since android DownloadManager will fail when// the url does not contains a file extension, by default the mime type will be text/plainmime :'text/plain',description :'File downloaded by download manager.'}}).fetch('GET','http://example.com/file/somefile').then((resp)=>{// the path of downloaded fileresp.path()})

Your app might not have right to remove/change the file created by Download Manager, therefore you might need toset custom location to the download task.

Download Notification and Visibility in Download App (Android Only)

If you need to display a notification upon the file is downloaded to storage (as the above) or make the downloaded file visible in "Downloads" app. You have to add some options toconfig.

RNFetchBlob.config({fileCache :true,// android only options, these options be a no-op on IOSaddAndroidDownloads :{// Show notification when response data transmittednotification :true,// Title of download notificationtitle :'Great ! Download Success ! :O ',// File description (not notification description)description :'An image file.',mime :'image/png',// Make the file scannable  by media scannermediaScannable :true,}}).fetch('GET','http://example.com/image1.png').then(...)

Open Downloaded File with Intent

This is a new feature added in0.9.0 if you're going to open a file path using officialLinking API that might not work as expected, also, if you're going to install an APK inDownloads app, that will not function too. As an alternative, you can tryactionViewIntent API, which will send an ACTION_VIEW intent for you which uses the givenMIME type.

Download and install an APK programmatically

constandroid=RNFetchBlob.androidRNFetchBlob.config({addAndroidDownloads :{useDownloadManager :true,title :'awesome.apk',description :'An APK that will be installed',mime :'application/vnd.android.package-archive',mediaScannable :true,notification :true,}}).fetch('GET',`http://www.example.com/awesome.apk`).then((res)=>{android.actionViewIntent(res.path(),'application/vnd.android.package-archive')})

Or show an image in image viewer

android.actionViewIntent(PATH_OF_IMG,'image/png')

File access APIs were made when developingv0.5.0, which helping us write tests, and was not planned to be a part of this module. However, we realized that it's hard to find a great solution to manage cached files, everyone who uses this module may need these APIs for their cases.

Before start using file APIs, we recommend readDifferences between File Source first.

File Access APIs

• asset (0.6.2)
• dirs
• createFile
• writeFile (0.6.0)
• appendFile (0.6.0)
• readFile (0.6.0)
• readStream
• writeStream
• unlink
• mkdir
• ls
• mv
• cp
• exists
• isDir
• stat
• lstat
• scanFile (Android only)

SeeFile API for more information

Inv0.5.0 we've addedwriteStream andreadStream, which allows your app read/write data from the file path. This API creates a file stream, rather than convert entire data into BASE64 encoded string. It's handy when processinglarge files.

When callingreadStream method, you have toopen the stream, and start to read data. When the file is large, consider using an appropriatebufferSize andinterval to reduce the native event dispatching overhead (seePerformance Tips)

The file stream event has a default throttle(10ms) and buffer size which preventing it cause too much overhead to main thread, yo can alsotweak these values.

letdata=''RNFetchBlob.fs.readStream(// file pathPATH_TO_THE_FILE,// encoding, should be one of `base64`, `utf8`, `ascii`'base64',// (optional) buffer size, default to 4096 (4095 for BASE64 encoded data)// when reading file in BASE64 encoding, buffer size must be multiples of 3.4095).then((ifstream)=>{ifstream.open()ifstream.onData((chunk)=>{// when encoding is `ascii`, chunk will be an array contains numbers// otherwise it will be a stringdata+=chunk})ifstream.onError((err)=>{console.log('oops',err)})ifstream.onEnd(()=>{<Imagesource={{uri :'data:image/png,base64'+data}}})})

When usingwriteStream, the stream object becomes writable, and you can then perform operations likewrite andclose.

RNFetchBlob.fs.writeStream(PATH_TO_FILE,// encoding, should be one of `base64`, `utf8`, `ascii`'utf8',// should data append to existing content ?true).then((ofstream)=>{ofstream.write('foo')ofstream.write('bar')ofstream.close()})

When usingfileCache orpath options along withfetch API, response data will automatically store into the file system. The files willNOT removed unless youunlink it. There're several ways to remove the files

// remove file using RNFetchblobResponse.flush() object methodRNFetchblob.config({fileCache :true}).fetch('GET','http://example.com/download/file').then((res)=>{// remove cached file from storageres.flush()})// remove file by specifying a pathRNFetchBlob.fs.unlink('some-file-path').then(()=>{// ...})

You can also group requests by usingsession API and usedispose to remove them all when needed.

RNFetchblob.config({fileCache :true}).fetch('GET','http://example.com/download/file').then((res)=>{// set session of a responseres.session('foo')})RNFetchblob.config({// you can also set session beforehandsession :'foo'fileCache :true}).fetch('GET','http://example.com/download/file').then((res)=>{// ...})// or put an existing file path to the sessionRNFetchBlob.session('foo').add('some-file-path')// remove a file path from the sessionRNFetchBlob.session('foo').remove('some-file-path')// list paths of a sessionRNFetchBlob.session('foo').list()// remove all files in a sessionRNFetchBlob.session('foo').dispose().then(()=>{ ...})

After0.9.4, theChunked transfer encoding is disabled by default due to some service provider may not support chunked transfer. To enable it, setTransfer-Encoding header toChunked.

RNFetchBlob.fetch('POST','http://example.com/upload',{'Transfer-Encoding' :'Chunked'},bodyData)

By default, react-native-fetch-blob does NOT allow connection to unknown certification provider since it's dangerous. To connect a server with self-signed certification, you need to addtrusty toconfig explicitly. This function is available for version >=0.5.3

RNFetchBlob.config({trusty :true}).then('GET','https://mysite.com').then((resp)=>{// ...})

After0.8.0 we've made someWeb API polyfills that makes some browser-based library available in RN.

• Blob
• XMLHttpRequest (Use our implementation if you're going to use it with Blob)

Here's asample app that uses polyfills to upload files to FireBase.

Read Stream and Progress Event Overhead

If the process seems to block JS thread when file is large when reading data viafs.readStream. It might because the default buffer size is quite small (4kb) which result in a lot of events triggered from JS thread. Try to increase the buffer size (for example 100kb = 102400) and set a larger interval (available for 0.9.4+, the default value is 10ms) to limit the frequency.

Reduce RCT Bridge and BASE64 Overhead

React Native connects JS and Native context by passing JSON around React Native bridge, and there will be an overhead to convert data before they sent to each side. When data is large, this will be quite a performance impact to your app. It's recommended to use file storage instead of BASE64 if possible.The following chart shows how much faster when loading data from storage than BASE64 encoded string on iPhone 6.

ASCII Encoding has /terrible Performance

Due to thelack of typed array implementation in JavascriptCore, and limitation of React Native structure, to convert data to JS byte array spends lot of time. Use it only when needed, the following chart shows how much time it takes when reading a file with different encoding.

Concat and Replacing Files

If you're going to concatenate files, you don't have to read the data to JS context anymore! In0.8.0 we introduced new encodinguri for writeFile and appendFile API, which make it possible to handle the whole process in native.

• This library does not urlencode unicode characters in URL automatically, see#146.
• When you create aBlob , from an existing file, the fileWILL BE REMOVED if youclose the blob.
• If you replacedwindow.XMLHttpRequest for some reason (e.g. make Firebase SDK work), it will also affect how officialfetch works (basically it should work just fine).
• When file stream and upload/download progress event slow down your app, consider an upgrade to0.9.6+, useadditional arguments to limit its frequency.
• When passing a file path to the library, removefile:// prefix.

when you got a problem, have a look atTrouble Shooting orissues labeled Trouble Shooting, there'd be some helpful information.

Seerelease notes

If you're interested in hacking this module, check ourdevelopment guide, there might be some helpful information.Please feel free to make a PR or file an issue.