cordova-plugin-file Alternative for Capacitor

The practical cordova-plugin-file alternative for a Capacitor migration is @capgo/capacitor-file. It mirrors the Cordova entry and reader model (requestFileSystem, resolveLocalFileSystemURL, getFile, getDirectory) while exposing promise-based readFile, writeFile, copy, move, and permission helpers that fit Capacitor apps on iOS, Android, and Web. This guide covers maintenance facts, install steps, a usage sample, and an API map from Cordova to Capgo.

Why leave cordova-plugin-file in a Capacitor app

cordova-plugin-file is still published. npm lists version 8.1.3 with a last publish date of 20 November 2024. The Apache repository on GitHub received commits in 2026, so the Cordova project is not abandoned.

In a Capacitor codebase the pain is integration, not npm freshness:

• The plugin expects window.requestLocalFileSystem, cordova.file.* constants, and callback-style FileReader / FileWriter objects.
• Other Cordova plugins (file transfer, media, chooser) still assume file:// or cdvfile:// paths that do not match Capacitor’s URI model.
• Capacitor’s own @capacitor/filesystem is excellent for greenfield apps but does not implement Cordova’s entry tree APIs, so large legacy codebases need a dedicated bridge.

@capgo/capacitor-file is built for that bridge. The README states the API is compatible with cordova-plugin-file and documents a migration table from Cordova calls to Capgo methods. It follows Capacitor major versions (v8.x for Capacitor 8) and includes iOS, Android, and Web implementations.

Install

bun add @capgo/capacitor-file
bunx cap sync

On Android 13+, call requestPermissions() only when your feature truly needs shared storage or broad media access. Google Play’s Photo and Video Permissions policy expects one-time picks (for example profile photos) to use a system picker such as @capgo/capacitor-file-picker instead of READ_MEDIA_IMAGES or READ_MEDIA_VIDEO. The plugin README links to Google’s policy for review requirements.

Run bunx cap sync after changing dependencies so native projects pick up the plugin. Ship the native change through your normal store build or Capgo Build.

Usage example

import { CapacitorFile, Directory, Encoding } from '@capgo/capacitor-file';

export async function saveConfig(json: string) {
  const path = 'config/app-settings.json';

  await CapacitorFile.writeFile({
    path,
    directory: Directory.Data,
    data: json,
    encoding: Encoding.UTF8,
    recursive: true,
  });

  const { data } = await CapacitorFile.readFile({
    path,
    directory: Directory.Data,
    encoding: Encoding.UTF8,
  });

  return JSON.parse(data) as Record<string, unknown>;
}

For Cordova-style URLs, resolve first then read:

const entry = await CapacitorFile.resolveLocalFileSystemURL({
  url: nativeFileUrl,
});
console.log(entry.name, entry.isFile);

Migrating from Cordova to Capacitor

Replace global Cordova file calls with CapacitorFile imports. Drop deviceready gates; await promises instead of success and error callbacks.

API mapping table

The mapping table above matches the plugin README migration section.

Path tips

• Replace cdvfile:// paths with Directory plus relative paths, or with URIs from CapacitorFile.getUri().
• To show a local image in the WebView, convert native paths with Capacitor.convertFileSrc().
• Plugins that still expect Cordova file URLs (old file transfer code) should be migrated or removed so every call site uses Capacitor URIs.

Links and next steps

• Plugin docs: https://capgo.app/docs/plugins/file/
• Marketing page: /plugins/capacitor-file/
• npm: https://www.npmjs.com/package/@capgo/capacitor-file
• GitHub: https://github.com/Cap-go/capacitor-file/

After native file code is on @capgo/capacitor-file, you can ship JavaScript fixes with Capgo live updates. For the full platform move, read our Cordova to Capacitor migration guide. If you also replace file transfer, see the cordova-plugin-file-transfer alternative.