cordova-plugin-file maps web File API calls onto device storage

A global object that only appears after deviceready

This plugin implements a File API allowing read and write access to files residing on the device, based on W3C specifications, and it does so by defining a global cordova.file object. The important detail is the second sentence of the same paragraph. Although the object is in the global scope, it is not available to applications until after the deviceready event fires, which is the Cordova pattern for native code becoming callable:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(cordova.file);
}

The consequence for anyone porting browser code is that every call site has to sit behind that event, and a plugin that assumes otherwise will fail on a cold start in a way that never reproduces in a browser. The specification base is three documents, the HTML5 File API, the File API for Directories and System, and the File API Writer, and the documentation carries a footnote that is easy to miss. These specifications are discontinued and the file plugin may not have the entire specification implemented. A note adds one more caveat. While the W3C FileSystem spec is deprecated for web browsers, the FileSystem APIs are supported in Cordova applications with this plugin for the platforms listed, with the exception of the Browser platform.

One directory per storage category, and each behaves differently

As of v1.2.0, URLs to important file system directories are provided, each in the form file:///path/to/spot/ and convertible to a DirectoryEntry with window.resolveLocalFileSystemURL(). The list is where the design decisions live. The application directory is where the app is installed and is read-only. The application storage directory is the root of the app sandbox, read-only on iOS except for specific subdirectories, with all data private to the app. The data directory is persistent and private storage using internal memory, with externalDataDirectory named as the Android alternative for external memory, and syncedDataDirectory named as the iOS alternative when you want iCloud sync. The cache directory is for files the app can recreate, and the documentation warns that the OS may delete them when storage runs low while also saying apps should not rely on the OS to do so. The temp directory can be cleared by the OS at will, and the instruction is that your app should always remove files as applicable. Several more are Android only, including the external root directory for the SD card, and the iOS only entries are the synced and documents directories, the latter for files that are private to the app but meaningful to other applications.

The storage choice is a durability decision, not a path

The reason the directory list is worth reading in full is that the name of a directory implies a behaviour you have to design around. Choosing the cache directory for a document your user created is a bug even though the write succeeds, because the system may remove it at a moment of its own choosing. Choosing the data directory means the file survives, but on iOS it is not synced with iCloud, and the documentation points you at the synced data directory when you want that. Choosing the documents directory on iOS means the file is private to your app but meaningful to other applications, for example Office files, which is a deliberate sharing decision rather than a storage tier. The external directories on Android split the same way, with external data for app specific files, external cache for the disposable kind, external application storage for application space, and the external root for the SD card itself. The plugin also documents how these map to physical device paths in a table, and it says so with the caveat that although technically an implementation detail, knowing the mapping is very useful.

Android external storage needs its own section of the docs

Four of the directory properties point to an Android quirks section, and the repetition is a signal. The external application storage, external data, external cache and external root directories all carry a note to see the Android external storage quirks, which is where the platform specific behaviour lives rather than in the general description. The reason this matters is that Android has changed its storage model more than once, and the difference between app specific external storage, which needs no permission, and shared external storage, which does, changes what your code can do. A plugin that exposed one directory name would hide that difference; this one exposes four, and then documents the differences separately. The same is true of iOS, where the table of device paths, the cordova.file property, the iosExtraFileSystems column, and columns for read and write, persistence, whether the OS clears it, sync and private, is the format that makes the platform differences comparable at a glance.

Install, platform support and the constraints on the API

Installation is the standard Cordova plugin add:

cordova plugin add cordova-plugin-file

The supported platforms are Android, iOS and Browser, and the package metadata lists exactly those three under the cordova key, with cordova-android, cordova-browser and cordova-ios among the keywords. The plugin works on the browser platform too, which is the point of a Cordova plugin, and the documentation points to the HTML5 Rocks FileSystem article for browser focused examples. The constraint on the API surface is stated in a single line. These platforms do not support FileReader.readAsArrayBuffer nor FileWriter.write(blob). That is a real limitation for anyone writing a modern file handling layer, since those are the two methods you would reach for when working with binary content, and the note carries an asterisk back to the list of supported platforms. There is also a broader pointer for anyone who is not sure whether they need this plugin, a link to the Cordova storage guide for an overview of other storage options, and a link to the sample at the bottom of the page.

An Apache project with a version that is not 1.0

The repository is an Apache Software Foundation project, with the LICENSE and NOTICE files at the root, the licence field in package.json reading Apache-2.0, and the plugin authored by the Apache Software Foundation. The version in package.json reads 9.0.0-dev, which is the interesting number. The Cordova plugin version and the Cordova dependency version are different axes, and the engines block in package.json maps the latter to platform requirements, so Cordova 5.0.0 maps to cordova-android at 6.3.0 or later, 7.0.0 maps to cordova-android 10.0.0, 8.0.0 maps to cordova-android 12.0.0, and 9.0.0 maps to cordova-android 13.0.0, cordova-ios 6.2.0 and cordova 11.0.0. A tenth Cordova dependency entry exists with a cordova requirement written as >100, which reads like a deliberate placeholder for a future major version rather than a usable constraint. The repository is not archived and the last push was on 2026-09-09, with no GitHub releases listed, and the tree carries the expected ASF furniture with a .asf.yaml, a licence_checker.yml, a RELEASENOTES.md, a rat-excludes file, and separate CI workflows for the node build, the Android, Chrome and iOS test suites, linting and a release audit.

Editorial conclusion

Adopt cordova-plugin-file when you maintain a Cordova application that still needs genuine file system access rather than the browser sandbox, and when you can work with the platform differences in storage directories. Do not adopt it expecting a complete implementation of the W3C File API, since the documentation says the specification is discontinued and the plugin may not implement all of it, and note the browser platform is the exception to the FileSystem support. Verify first that the storage directory you choose matches what the operating system will clear, that you use the right platform directory for what you are storing, and that the FileReader and FileWriter methods you need are supported on the platforms you ship to.

Frequently asked questions

Official sources

1. apache/cordova-plugin-file on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README