PhoneGap/Cordova File System questions

This post is more than 2 years old.

A large majority of the questions I get about PhoneGap and Cordova revolve around the file system API. It has had some pretty significant updates recently but still remains one of the most difficult ones to use. I've been putting off really digging deep into those questions because many times they are incredibly specific to a particular user's application. And - honestly - they typically don't lend themselves to the type of quick questions I can answer during the day.

So with that in mind, I thought it might be fruitful to ask my readers about the API and how I can help make things a bit clearer - for both you and me. What I'm thinking is - can we come up with a list of basic questions, a FAQ perhaps, for just this API. It can't be something too precise to one particular application, but something that can apply to multiple users.

As an example: How do I download an asset to my application? That's a simple question, but it brings up the question of where you would download the asset and how you would actually use it later.

Of course, the big issue is that this particular API is an evolving one. Anything I do today will be outdated next year. But as most of my blog posts on the API are already over a year old, this would at least be a bit fresher. ;)

In order to organize this list, I'm going to start it in the blog entry. Use the comments to make suggestions, and as I see ones that I think make sense, I'll add them to the list. By the way, I know some of these are super trivial, but I figure it doesn't hurt to try to cover as much as possible.

File System FAQ

  • When does it make sense to use the file system (versus LocalStorage or WebSQL)?
  • How do I download an asset to my application?
  • How do I use a file stored in the file system (both binary and text-based files)?
  • How do I check to see if a file exists in a directory?
  • Are there external tools that can check a device's file system?
  • How do I check to see if a directory exists?
  • How do I make a subdirectory where the parent directory may not exist?
  • Are there any app store restrictions/guidelines for using the file system?
  • For iOS, where can I store files so that they will be backed up to iCloud?
  • How can I get metadata (size, updated) about a file?
Raymond Camden's Picture

About Raymond Camden

Raymond is a senior developer evangelist for Adobe. He focuses on document services, JavaScript, and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA

Archived Comments

Comment 1 by Lasse Lundin posted on 6/24/2014 at 3:14 PM

Hi Raymond.

Regarding some of the questions i found a program for my mac to check directories on an iPad.
It's called iFunBox and shows the directories associated with your app. Really nifty if you want to check if a picture is stored persistently or check if filename is correct.
Its really easy to use, so hope it helps. Also as I recall it's free.

Comment 2 by Raymond Camden posted on 6/24/2014 at 6:07 PM

Oh, that's an excellent suggestion Lasse. If I'm writing code that just downloads crap and I don't need to read it, or I'm not there yet, and I just want to quickly scan the directory, using an external app like that would be *much* quicker! I'll add it to the list.

Comment 3 by Kevin Quinn posted on 6/24/2014 at 9:49 PM

general guidelines to live under Apple's rules on storage.

Comment 4 by Kevin Quinn posted on 6/24/2014 at 9:51 PM

how to mark downloaded files to be backed up (or not) on iOS.

Comment 5 by Kevin Quinn posted on 6/24/2014 at 9:57 PM

how to reference app content from html you download into Internal/Library space?

('../../../' on iOS and 'file:///android_asset/www' for Android)

Comment 6 by Raymond Camden posted on 6/24/2014 at 10:53 PM

Good ones. I added the first two, but I think the third is already covered.

Comment 7 by Greg Hudy posted on 6/25/2014 at 12:56 AM

Another mac app that I use for checking files on the iPad is iExplorer ( )
I have dealt quite a bit with the File API, but these are some that I am not aware of.
1. File size limit that can be added to the device?
2. Show progress of file creation?

I have done these but if you are creating a list, it might be good to have here
3. Show file download progress

Comment 8 by Kevin Quinn posted on 6/25/2014 at 12:56 AM

really? I had to cook it up myself since I couldn't find it anywhere.

can you give me a pointer where to look?

Comment 9 by Raymond Camden posted on 6/25/2014 at 1:02 AM

@Kevin: I meant your question was already listed. "How do I use a file stored in the file system (both binary and text-based files)?"

@Greg: I think 1 can be covered in question 2: "How do I download an asset to my application?" Ditto for your second question. To me it is contained in there. (And if it becomes too complex, we break it out.)

Comment 10 by Kevin Quinn posted on 6/25/2014 at 2:08 AM

gotcha. thanks Raymond.

another one would be "how to check if a file is X minutes old?"

right now it's broken on Android so maybe list a workaround.

Comment 11 by Raymond Camden posted on 6/25/2014 at 6:44 AM

@Kevin: I like that, but modified it to be a bit more open (metadata). Added to the list.

Comment 12 by Sunoj Vijayan posted on 6/25/2014 at 11:49 AM


Please correct me if I am wrong, but it would be nice if we could download a file to specific folder(say 'appimages") inside my application folder.

Comment 13 by Kelvin Dart posted on 6/25/2014 at 11:59 AM

Hi Raymond,

I have had a generic File API question that has always bugged me (which can be found on stackoverflow: But to save a click, the question is as follows:

I am trying to figure out why there are currently six alternate methods/properties to access the path of a file.

Currently (running using iOS), there is:
// Properties
file.fullPath; // file:///full/path/syntax/file
file.nativeURL; // file:///full/path/syntax/file

// Method(s)
file.toInternalURL(); // formats the file.fullPath into a cdvfile://localhost/persisten/file.
file.toURL(); // if file.nativeURL is set, uses file.nativeURL, otherwise use file.toInternalURL() or file.fullPath.

// Deprecated method(s)
file.toURI(); // deprecated - calls file.toURL();
file.toNativeURL() // deprecated - calls file.toURL();

I understand two are deprecated - which both point to file.toURL() - so I can ignore them and focus on just four methods.

But what is the difference between file.fullPath and file.nativeURL - they are exactly the same? They are both properties on the file object - both publicly accessible.

As far as I can tell, file.toURL() uses both of these - first file.nativeURL if not that, then file.toInternalURL() or failing that, then file.fullPath.

Then finally, file.toNativeURL() returns a cdvfile:// formatted location.

So, most methods point to the file.nativeURL property. Is file.toURL() the method to use since it handles all instances? If so, then what on earth is cdvfile://?


Comment 14 by Nathan Prather posted on 6/25/2014 at 12:02 PM

I'm working on a phonegap app right now that will need to allow users to download a zip file from a vendors website and upload it into my app so this information will be very helpful to me... Thanks!

Comment 15 by Raymond Camden posted on 6/25/2014 at 6:01 PM

@Sunoj: I believe that is covered in the list already.
@Nathan: I've done "download a zip and extract" before, but not in PhoneGap. But the code should be very similar:

Comment 16 by Greg Hudy posted on 6/25/2014 at 6:18 PM

@Nathan Here is a PG plugin that might be of use to you. I have used it before and it worked well for my needs -

Comment 17 by Nathan Prather posted on 6/25/2014 at 9:43 PM

Awesome! Thanks for your help @Raymond and @Greg! I'll check out both of these...

Comment 18 by Raymond Camden posted on 6/28/2014 at 11:13 PM

I've started writing here: (removed - doc is now published)

Comment 19 by amiel asparen posted on 7/5/2014 at 12:48 PM

hey i need help. im making an app on a android driven tablet using dreamweaver cc when i used the PHONE GAP BUILD SERVICE to build my project and the i download it and intall it to my device

i get this respone

Hey it phone gap!!

and that it

o by that way a newbie in the app developing

need your immediate help T.T

Comment 20 by Raymond Camden posted on 7/5/2014 at 6:43 PM

Weird - sorry - not sure what to recommend outside of the DD forums.

Comment 21 by Lugo posted on 8/8/2014 at 2:11 AM

Hi Raymond!

actually i try create a list of all element of directory whit cordova on my ipad....but a can't!..

I really frustred......

I try whit this code:
function success(entries) {
var i;
for (i=0; i<entries.length; i++) {

function fail(error) {
alert("Failed to list directory contents: " + error.code);

// Get a directory reader
var directoryReader = dirEntry.createReader();

// Get a list of all the entries in the directory

but the code is broke in this line "var directoryReader = dirEntry.createReader();".

Any suggestions?

PD: Sorry for my bad english :P

Comment 22 by Raymond Camden posted on 8/8/2014 at 10:22 PM

This post is not really for generic tech support. I did ask people to make suggestions about things to cover - and directory reading is already there. Please post your question to the PhoneGap google group or Stack Overflow.

Comment 23 by Román Suárez posted on 9/25/2014 at 12:08 AM

Hi, do you have any example for creating and writing on a txt file, using cordova.file plugin?

Comment 24 by Raymond Camden posted on 9/25/2014 at 12:10 AM
Comment 25 by Raymond Camden posted on 9/29/2014 at 2:46 PM

For people looking for the doc, it is found here now:

Comment 26 by Kris posted on 1/28/2015 at 2:00 PM

I'd really like to see a simple snippet of code which is a non-platform-non-version-specific way of writing a local file using, and then accessing it using the Media plugin.