Nuanced Pumpkin Mavens


    1.2.5 • Public • Published


    Wraps the Cordova (and Chrome) File API in convenient functions (that return a Promise)

    Are you entangled in a async callback mess to get even the simplest task done? Wait no longer -- here is cordova-promise-fs!

    Getting started

      # fetch code using bower 
      bower install cordova-promise-fs
      bower install bluebird # a library that follows the Promise/A+ spec 
      # ...or npm... 
      npm install cordova-promise-fs
      npm install bluebird # a library that follows the Promise/A+ spec 
      # install Cordova and plugins 
      cordova platform add ios
      cordova plugin add cordova-plugin-file
      cordova plugin add cordova-plugin-file-transfer # optional 

    IMPORTANT: For iOS, use Cordova 3.7.0 or higher (due to a bug that affects requestFileSystem).

    Or just download and include CordovaPromiseFS.js.


    Initialize & configuration

    var fs = CordovaPromiseFS({
      persistent: true, // or false
      storageSize: 20*1024*1024, // storage size in bytes, default 20MB
      concurrency: 3 // how many concurrent uploads/downloads?
      Promise: require('promiscuous') // Your favorite Promise/A+ library!

    The Promise option expects a Promise library that follows the Promise/A+ spec, such as bluebird (github, download), promiscuous (github,file) or Angular's $q.

    Note on concurrency: Concurrent uploads/downloads completely trash your mobile application. That's why I've put a concurrency limit on the number of downloads/uploads. Meteor sets this number on 30. In my experimental testing, I found 3 much more reasonable.

    Browsing files

    fs.exists(filename)       // checks if file exists. returns fileEntry or false.
    fs.file(filename)         // returns a fileEntry
    fs.dir(path)              // returns a dirEntry
    fs.list(path,optionString)// return array with filenames (including path)
    optionString = 'r'        // recursive list
    optionString = 'd'        // only list directories
    optionString = 'f'        // only list files
    optionString = 'e'        // return results as FileEntry/DirectoryEntry (instead as path-string)
    optionString = 'rfe'      // mix options! return entries of all files, recursively

    Reading files         // returns text-content of a file
    fs.readJSON(filename)     // returns JSON-parsed contents of a file
    fs.toUrl(filename)        // returns URL to be used in js/html/css (file://....)
    fs.toInternalURL(filename)// returns cordova internal URL (cdvfile://....)
    fs.toDataURL(filename)    // returns Base64 encoded Data URI

    Writing files

    fs.write(filename,data)   // writes a Blob, a String, or data (as JSON). Ensures directory exists.

    File operations

    fs.create(filename)       // creates a file
    fs.ensure(path)           // ensures directory exists
    fs.move(src,dest)         // move from src to dist. Ensures dest directory exists.
    fs.copy(src,dest)         // copy from src to dist. Ensures dest directory exists.
    fs.remove(src)            // removes file. Resolves even if file was already removed.
    fs.remove(src,true)       // removes file. Rejects when file does not exist.

    Upload and download

    FileTransfers with automatric retry and concurrency limit!

    var promise = fs.upload(source,destination,[options],[onprogress]);
    var promise = fs.upload(source,destination,[onprogress]);
    var promise =,destination,[options],[onprogress]);
    var promise =,destination,[onprogress]);
    options.retry = [1000,2000,3000] // retry attemps: millisecond to wait before trying again.
    // plus all normal cordova-file-transfer options
    // upload/download augments the promise with two extra functions:
    // Gotcha: progress and abort() are unchainable;
    fs.upload(...).then(...)  // won't return the augmented promise, just an ordinary one!


    fs.fs // returns promise for the FileSystem
    fs.filename(path) // converts path to filename (last part after /)
    fs.dirname(path) // converts path dirname (everything except part after last /)
    fs.deviceready // deviceready promise
    fs.options // options
    fs.isCordova // is Cordova App?

    Normalized path

    In CordovaPromiseFS, all filenames and paths are normalized:

    • Directories should end with a /.
    • Filenames and directories should never start with a /.
    • "./" is converted to ""
    • ".." and "." are resolved.

    This allows you to concatenate normalized paths, i.e.

    normalize('dir1/dir2') === normalize('dir1') + normalize('dir2') === 'dir1/dir2/';

    If you're storing or saving paths, it is recommended to normalize them first to avoid comparison problems. (i.e. paths are not recognized as the same because of a missing trailing slash).

    Beware: the original entry.fullPath might return a path which starts with a /. This causes problems on Android, i.e.

    var path = filesystem.root.fullPath; // returns something starting with a `/`
    filesystem.root.getDirectory(path); // NullPointer error in android. Stupid!

    This problem is solved in CordovaPromiseFS.


    1.2.5 (05/05/2017)

    • Added Crosswalk
    • Bugfix: list will return more than 100 entries

    1.1.0 (05/05/2016)

    • Fixed bug: download/upload support for different Cordova FileSystems.

    1.0.0 (07/02/2016)

    • Fixed bug in list function, thanks @sebastian-greco
    • Improved code readability of transfer, thanks @youjenli
    • There is no this, thanks @m0ppers
    • Accept string as FileSystem, thanks @dortzur
    • Normalize ".." in paths, thanks @starquake

    0.13.0 (16/09/2015)

    • Merged pull request from @Ijzerenhein. Fixed Chrome Persistent storage quota issue and added directory methods.

    0.12.0 (17/03/2015)

    • Merged pull request from @jakgra. Now you can write to hidden folders on Android. Thanks!

    0.11.0 (17/03/2015)

    • Minor improvements in upload

    0.10.0 (21/12/2014)

    • Support for other fileSystems (undocumented hack)

    0.9.0 (28/11/2014)

    • Normalize path everywhere.

    0.8.0 (27/11/2014)

    • Added test-suite, fixed few minor bugs.

    0.7.0 (14/11/2014)

    • bugfix toInternalURL functions and fix download argument order

    0.6.0 (13/11/2014)

    • Chrome Support!

    0.5.0 (06/11/2014)

    • Use webpack for the build proces
    • Fixed many small bugs

    0.4.0 (06/11/2014)

    • Various small changes
    • Added CordovaPromiseFS.js for everybody who does not use Browserify/Webpack

    0.3.0 (05/11/2014)

    • Added list options (list recursively, only files, only directories, return result as entries)

    0.2.0 (05/11/2014)

    • Added upload and download methods with concurrency limit


    Convert CommonJS to a browser-version:

    npm install webpack -g
    npm run-script prepublish

    Run tests: Navigate to /test/index.html, for example:

    npm install static -g
    static .
    # http://localhost:8080/test/index.html 

    Feel free to contribute to this project in any way. The easiest way to support this project is by giving it a star.


    © 2014 - Mark Marijnissen


    npm i cordova-promise-fs

    DownloadsWeekly Downloads






    Last publish


    • markmarijnissen