{"id":44613,"library":"cordova-file-cache","title":"Cordova File Cache","description":"Cordova File Cache is a library for caching remote files (images, documents, etc.) in Cordova/PhoneGap apps. It provides a promise-based API using CordovaPromiseFS and supports hash or mirror caching modes. Version 1.2.2 is the latest stable release. It requires cordova-plugin-file and optionally cordova-plugin-file-transfer. Unlike ad-hoc caching strategies, it offers a structured cache with readiness promises, progress tracking, and automatic server URL fallback. Release cadence is low; the package is stable but not actively maintained.","status":"maintenance","version":"1.2.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/markmarijnissen/cordova-file-cache","tags":["javascript","cordova","file","cache"],"install":[{"cmd":"npm install cordova-file-cache","lang":"bash","label":"npm"},{"cmd":"yarn add cordova-file-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add cordova-file-cache","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for file system operations (CordovaPromiseFS instance)","package":"cordova-promise-fs","optional":false},{"reason":"Required Cordova plugin for file access","package":"cordova-plugin-file","optional":false}],"imports":[{"note":"The library exposes a global CordovaFileCache object; no import statement is used. Include the script tag or bundle via <script src='CordovaFileCache.js'></script>.","symbol":"CordovaFileCache","correct":"const CordovaFileCache = window.CordovaFileCache;"},{"note":"Required dependency, also a global. Must be loaded before CordovaFileCache.","symbol":"CordovaPromiseFS","correct":"const CordovaPromiseFS = window.CordovaPromiseFS;"},{"note":"The CordovaPromiseFS instance is mandatory and must include a Promise implementation.","wrong":"var cache = new CordovaFileCache({ mode: 'hash' }); // missing fs","symbol":"Cache instantiation","correct":"var cache = new CordovaFileCache({ fs: new CordovaPromiseFS({ Promise: Promise }), mode: 'hash' });"}],"quickstart":{"code":"<!-- Include Cordova, plugins, and promise library first -->\n<script src=\"cordova.js\"></script>\n<script src=\"bluebird.js\"></script>\n<script src=\"CordovaPromiseFS.js\"></script>\n<script src=\"CordovaFileCache.js\"></script>\n<script>\n// Initialize cache after device ready\ndocument.addEventListener('deviceready', function() {\n    var cache = new CordovaFileCache({\n        fs: new CordovaPromiseFS({\n            Promise: Promise  // using native Promise or bluebird\n        }),\n        mode: 'hash',\n        localRoot: 'cache',\n        serverRoot: 'https://example.com/files/',\n        cacheBuster: true\n    });\n\n    cache.ready.then(function(cachedList) {\n        console.log('Cache ready, cached paths:', cachedList);\n        // Add files\n        cache.add('photo1.jpg'); // prepends serverRoot\n        cache.download().then(function(cache) {\n            var internalUrl = cache.get('photo1.jpg');\n            // internalUrl like 'cdvfile://localhost/persistent/cache/xxx.jpg'\n            console.log('Cached file URL:', internalUrl);\n        });\n    });\n});\n</script>","lang":"javascript","description":"Complete setup and usage example: initialize cache, add a file, download, and retrieve cached URL."},"warnings":[{"fix":"Always provide fs option with a CordovaPromiseFS that has Promise property.","message":"CordovaPromiseFS instance is required and must include a Promise implementation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update Cordova to >=3.7.0.","message":"For iOS, Cordova 3.7.0 or higher is required due to a bug in requestFileSystem.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Provide serverRoot option in constructor or use 'hash' mode.","message":"When using 'mirror' mode, serverRoot is required.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Load via script tags; not compatible with ES imports or CommonJS.","message":"The library uses global window.CordovaFileCache; not a module system.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.2.2':37 'activ':87 'ad':58 'ad-hoc':57 'api':26 'app':19 'automat':73 'base':25 'cach':3,6,11,34,60,66,92 'cadenc':78 'cordova':1,4,46,52,90 'cordova-plugin-fil':45 'cordova-plugin-file-transf':51 'cordova/phonegap':18 'cordovapromisef':28 'document':15 'etc':16 'fallback':76 'file':2,5,13,48,54,91 'hash':31 'hoc':59 'imag':14 'javascript':89 'latest':40 'librari':9 'low':80 'maintain':88 'mirror':33 'mode':35 'offer':63 'option':50 'packag':82 'plugin':47,53 'progress':70 'promis':24,69 'promise-bas':23 'provid':21 'readi':68 'releas':42,77 'remot':12 'requir':44 'server':74 'stabl':41,84 'strategi':61 'structur':65 'support':30 'track':71 'transfer':55 'unlik':56 'url':75 'use':27 'version':36","created_at":"2026-06-07T12:50:59.236233+00:00","updated_at":"2026-06-07T12:50:59.236233+00:00","problems":[{"fix":"Ensure fs is a valid CordovaPromiseFS instance and that cordova-plugin-file is installed.","cause":"CordovaPromiseFS instance not provided or not initialized properly (missing directory).","error":"TypeError: Cannot read property 'root' of undefined"},{"fix":"Include CordovaPromiseFS.js before CordovaFileCache.js.","cause":"CordovaPromiseFS.js script not loaded before CordovaFileCache.js.","error":"CordovaPromiseFS is not defined"},{"fix":"Check constructor options: ensure fs and mode are correct.","cause":"Cache object not properly initialized or mode is invalid.","error":"TypeError: cache.download is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/markmarijnissen/cordova-file-cache#readme","github":"ssh://git@github.com/markmarijnissen/cordova-file-cache","docs":null,"changelog":null,"pypi":null,"npm":"cordova-file-cache","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}