@capgo/capacitor-file

January 31, 2026 · View on GitHub

➡️ Get Instant updates for your App with Capgo

Missing a feature? We'll build the plugin for you 💪

Capacitor plugin for file system operations. A modern replacement for cordova-plugin-file with a compatible API.

Why Capacitor File?

A reliable native file system plugin built for Capacitor apps with advanced features not available in the official Filesystem plugin:

Partial file reading - Read specific portions of files with offset and length parameters (great for large files)
Random access writes - Write at specific byte positions with position parameter
Cordova compatible API - Familiar methods like requestFileSystem(), resolveLocalFileSystemURL(), getFile(), and getDirectory()
All platform directories - Access Documents, Library, Cache, External storage and more
Progress events - Monitor read/write operations with real-time progress updates
Free and open source - No paid services required

Perfect for apps that need to work with large files, migrate from Cordova, or require random access file operations.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/file/

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

npm install @capgo/capacitor-file
npx cap sync

API

requestFileSystem(...)
resolveLocalFileSystemURL(...)
getFile(...)
getDirectory(...)
readFile(...)
readAsDataURL(...)
writeFile(...)
appendFile(...)
deleteFile(...)
mkdir(...)
rmdir(...)
readdir(...)
stat(...)
getMetadata(...)
rename(...)
move(...)
copy(...)
exists(...)
getUri(...)
truncate(...)
getDirectories()
getFreeDiskSpace()
addListener('readProgress', ...)
addListener('writeProgress', ...)
removeAllListeners()
getPluginVersion()
checkPermissions()
requestPermissions(...)
Interfaces
Type Aliases
Enums

Capacitor File Plugin Implements file system operations similar to the Cordova File plugin

Param	Type	Description
`options`	`RequestFileSystemOptions`	- File system request options

resolveLocalFileSystemURL(...)

resolveLocalFileSystemURL(options: ResolveURLOptions) => Promise<Entry>

Resolve a file URL to an entry.

Param	Type	Description
`options`	`ResolveURLOptions`	- URL to resolve

Returns: Promise<Entry>

Param	Type	Description
`options`	`GetFileOptions`	- File path and options

Param	Type	Description
`options`	`GetDirectoryOptions`	- Directory path and options

readAsDataURL(...)

readAsDataURL(options: ReadFileOptions) => Promise<{ data: string; }>

Read a file as a data URL (base64 with MIME type prefix).

Param	Type	Description
`options`	`ReadFileOptions`	- Read options

Returns: Promise<{ data: string; }>

Param	Type	Description
`options`	`WriteFileOptions`	- Write options

Param	Type	Description
`options`	`WriteFileOptions`	- Write options (append is forced to true)

deleteFile(...)

deleteFile(options: DeleteFileOptions) => Promise<void>

Delete a file.

Param	Type	Description
`options`	`DeleteFileOptions`	- Delete options

mkdir(...)

mkdir(options: MkdirOptions) => Promise<void>

Create a directory.

Param	Type	Description
`options`	`MkdirOptions`	- Directory creation options

rmdir(...)

rmdir(options: DeleteDirectoryOptions) => Promise<void>

Delete a directory.

Param	Type	Description
`options`	`DeleteDirectoryOptions`	- Delete options

Param	Type	Description
`options`	`ReaddirOptions`	- Read options

Param	Type	Description
`options`	`StatOptions`	- Stat options

Param	Type	Description
`options`	`StatOptions`	- Stat options

rename(...)

rename(options: RenameOptions) => Promise<void>

Rename or move a file or directory.

Param	Type	Description
`options`	`RenameOptions`	- Rename options

move(...)

move(options: RenameOptions) => Promise<void>

Move a file or directory. Alias for rename().

Param	Type	Description
`options`	`RenameOptions`	- Move options

Param	Type	Description
`options`	`CopyOptions`	- Copy options

Param	Type	Description
`options`	`ExistsOptions`	- Check options

Param	Type	Description
`options`	`GetUriOptions`	- URI options

truncate(...)

truncate(options: TruncateOptions) => Promise<void>

Truncate a file to a specified size.

Param	Type	Description
`options`	`TruncateOptions`	- Truncate options

getDirectories()

getDirectories() => Promise<FileDirectories>

Get all known file system directories.

Returns: Promise<FileDirectories>

getFreeDiskSpace()

getFreeDiskSpace() => Promise<{ free: number; }>

Get the free disk space in bytes.

Returns: Promise<{ free: number; }>

addListener('readProgress', ...)

addListener(eventName: 'readProgress', listenerFunc: (progress: ProgressEvent) => void) => Promise<PluginListenerHandle>

Listen for read progress events.

Param	Type	Description
`eventName`	`'readProgress'`	- Must be 'readProgress'
`listenerFunc`	`(progress: ProgressEvent) => void`	- Callback receiving progress updates

Returns: Promise<PluginListenerHandle>

addListener('writeProgress', ...)

addListener(eventName: 'writeProgress', listenerFunc: (progress: ProgressEvent) => void) => Promise<PluginListenerHandle>

Listen for write progress events.

Param	Type	Description
`eventName`	`'writeProgress'`	- Must be 'writeProgress'
`listenerFunc`	`(progress: ProgressEvent) => void`	- Callback receiving progress updates

Returns: Promise<PluginListenerHandle>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the plugin version.

Returns: Promise<{ version: string; }>

checkPermissions()

checkPermissions() => Promise<FilePermissionStatus>

Check the current permission status for file operations. On Android, this checks for external storage permissions. On iOS and web, this always returns 'granted' as no special permissions are needed.

Returns: Promise<FilePermissionStatus>

requestPermissions(...)

requestPermissions(options?: PermissionRequestOptions | undefined) => Promise<FilePermissionStatus>

Request permissions for file operations. On Android, this requests external storage permissions needed for accessing files outside the app's private directories. On iOS and web, this always returns 'granted' as no special permissions are needed.

Param	Type	Description
`options`	`PermissionRequestOptions`	- Optional configuration for the permission request

Returns: Promise<FilePermissionStatus>

Interfaces

FileSystem

Represents a file system

Prop	Type	Description
`name`	`string`	The name of the file system
`root`	`DirectoryEntry`	The root directory of the file system

DirectoryEntry

Represents a directory entry

Prop	Type	Description
`isFile`	`false`	True if this is a file
`isDirectory`	`true`	True if this is a directory

RequestFileSystemOptions

Options for requesting a file system

Prop	Type	Description
`type`	`FileSystemType`	The type of file system to request
`size`	`number`	Requested size in bytes (may not be enforced on all platforms)

Entry

Represents a file or directory entry

Prop	Type	Description
`isFile`	`boolean`	True if this is a file
`isDirectory`	`boolean`	True if this is a directory
`name`	`string`	The name of the file or directory
`fullPath`	`string`	The full path relative to the filesystem root
`nativeURL`	`string`	The native file:// URI

ResolveURLOptions

Options for resolving a URL to an entry

Prop	Type	Description
`url`	`string`	The URL to resolve (file:// or cdvfile://)

FileEntry

Represents a file entry

Prop	Type	Description
`isFile`	`true`	True if this is a file
`isDirectory`	`false`	True if this is a directory

GetFileOptions

Options for getting a file

Prop	Type	Description
`path`	`string`	Path to the file
`directory`	`Directory`	Base directory
`options`	`GetOptions`	Options for creating the file

GetOptions

Options for creating or getting files/directories

Prop	Type	Description
`create`	`boolean`	Create the file/directory if it doesn't exist
`exclusive`	`boolean`	If true and create is true, throw error if file/directory already exists

GetDirectoryOptions

Options for getting a directory

Prop	Type	Description
`path`	`string`	Path to the directory
`directory`	`Directory`	Base directory
`options`	`GetOptions`	Options for creating the directory

ReadFileResult

Result of reading a file

Prop	Type	Description
`data`	`string`	File contents as string (text) or base64 (binary)

ReadFileOptions

Options for reading a file

Prop	Type	Description
`path`	`string`	Path to the file
`directory`	`Directory`	Base directory
`encoding`	`Encoding`	Encoding for text files (omit for binary/base64)
`offset`	`number`	Byte offset to start reading from (default: 0)
`length`	`number`	Number of bytes to read (default: read to end of file)

WriteFileResult

Result of writing a file

Prop	Type	Description
`uri`	`string`	The URI of the written file

WriteFileOptions

Options for writing a file

Prop	Type	Description
`path`	`string`	Path to the file
`directory`	`Directory`	Base directory
`data`	`string`	Data to write (string for text, base64 for binary)
`encoding`	`Encoding`	Encoding for text files
`append`	`boolean`	If true, append to existing file instead of overwriting
`recursive`	`boolean`	Create intermediate directories if they don't exist
`position`	`number`	Byte position to start writing at (for random access writes). If not specified, writes from beginning or appends based on 'append' flag

DeleteFileOptions

Options for deleting a file or directory

Prop	Type	Description
`path`	`string`	Path to the file or directory
`directory`	`Directory`	Base directory

MkdirOptions

Options for creating a directory

Prop	Type	Description
`path`	`string`	Path to the directory
`directory`	`Directory`	Base directory
`recursive`	`boolean`	Create intermediate directories if they don't exist

DeleteDirectoryOptions

Options for deleting a directory recursively

Prop	Type	Description
`path`	`string`	Path to the directory
`directory`	`Directory`	Base directory
`recursive`	`boolean`	If true, delete contents recursively

ReaddirResult

Result of reading a directory

Prop	Type	Description
`entries`	`Entry[]`	List of entries in the directory

ReaddirOptions

Options for reading a directory

Prop	Type	Description
`path`	`string`	Path to the directory
`directory`	`Directory`	Base directory

StatResult

Result of getting file/directory information

Prop	Type	Description
`type`	`'file' \| 'directory'`	Type: 'file' or 'directory'
`size`	`number`	Size in bytes
`ctime`	`number`	Creation time (if available)
`mtime`	`number`	Last modification time
`uri`	`string`	The URI

StatOptions

Options for getting file information

Prop	Type	Description
`path`	`string`	Path to the file or directory
`directory`	`Directory`	Base directory

Metadata

Represents metadata about a file or directory

Prop	Type	Description
`modificationTime`	`number`	Last modification date
`size`	`number`	Size in bytes (0 for directories)

RenameOptions

Options for renaming/moving a file or directory

Prop	Type	Description
`from`	`string`	Current path
`to`	`string`	New path
`directory`	`Directory`	Base directory for 'from' path
`toDirectory`	`Directory`	Base directory for 'to' path

CopyResult

Result of copy operation

Prop	Type	Description
`uri`	`string`	The URI of the copied file

CopyOptions

Options for copying a file or directory

Prop	Type	Description
`from`	`string`	Source path
`to`	`string`	Destination path
`directory`	`Directory`	Base directory for source
`toDirectory`	`Directory`	Base directory for destination

ExistsResult

Result of existence check

Prop	Type	Description
`exists`	`boolean`	True if the file or directory exists
`type`	`'file' \| 'directory'`	Type if exists: 'file' or 'directory'

ExistsOptions

Options for checking if a file or directory exists

Prop	Type	Description
`path`	`string`	Path to check
`directory`	`Directory`	Base directory

GetUriResult

Result of getting a URI

Prop	Type	Description
`uri`	`string`	The native URI

GetUriOptions

Options for getting the URI of a file

Prop	Type	Description
`path`	`string`	Path to the file
`directory`	`Directory`	Base directory

TruncateOptions

Options for truncating a file

Prop	Type	Description
`path`	`string`	Path to the file
`directory`	`Directory`	Base directory
`size`	`number`	Size to truncate to (default: 0)

FileDirectories

Known file system directories exposed by the plugin

Prop	Type	Description
`applicationDirectory`	`string`	Application installation directory (read-only)
`applicationStorageDirectory`	`string`	Application storage directory root
`dataDirectory`	`string`	Persistent private data directory
`cacheDirectory`	`string`	Cache directory
`externalRootDirectory`	`string`	External root directory (Android)
`externalApplicationStorageDirectory`	`string`	External application storage directory (Android)
`externalDataDirectory`	`string`	External data directory (Android)
`externalCacheDirectory`	`string`	External cache directory (Android)
`documentsDirectory`	`string`	Documents directory (iOS)
`syncedDataDirectory`	`string`	Synced data directory (iOS iCloud)
`libraryDirectory`	`string`	Library directory (iOS)
`tempDirectory`	`string`	Temporary directory

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

ProgressEvent

Progress event for file operations

Prop	Type	Description
`loaded`	`number`	Bytes loaded so far
`total`	`number`	Total bytes (if known)
`lengthComputable`	`boolean`	Whether total is computable

FilePermissionStatus

Permission status for file operations

Prop	Type	Description
`publicStorage`	`PermissionState`	Permission state for reading public/external storage

PermissionRequestOptions

Options for requesting permissions

Prop	Type	Description	Default
`showSettingsAlert`	`boolean`	If true, shows an alert to open settings when permission is denied	`false`
`title`	`string`	Title for the settings alert dialog
`message`	`string`	Message for the settings alert dialog
`openSettingsButtonTitle`	`string`	Text for the "Open Settings" button
`cancelButtonTitle`	`string`	Text for the "Cancel" button

Members	Value
`TEMPORARY`	`0`
`PERSISTENT`	`1`

Encoding

Members	Value
`UTF8`	`'utf8'`
`ASCII`	`'ascii'`
`UTF16`	`'utf16'`

Usage Examples

Reading a File

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

// Read as text
const result = await CapacitorFile.readFile({
  path: 'my-file.txt',
  directory: Directory.Documents,
  encoding: Encoding.UTF8,
});
console.log(result.data);

// Read as base64 (binary)
const binaryResult = await CapacitorFile.readFile({
  path: 'image.png',
  directory: Directory.Documents,
});
console.log(binaryResult.data); // base64 string

// Read partial file (offset and length) - great for large files!
const partialResult = await CapacitorFile.readFile({
  path: 'large-file.bin',
  directory: Directory.Documents,
  offset: 1024,    // Start at byte 1024
  length: 512,     // Read 512 bytes
});
console.log(partialResult.data); // base64 encoded chunk

Writing a File

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

// Write text
await CapacitorFile.writeFile({
  path: 'my-file.txt',
  directory: Directory.Documents,
  data: 'Hello, World!',
  encoding: Encoding.UTF8,
  recursive: true, // Create parent directories if needed
});

// Write binary (base64)
await CapacitorFile.writeFile({
  path: 'image.png',
  directory: Directory.Documents,
  data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
});

// Write at specific position (random access) - great for patching files!
await CapacitorFile.writeFile({
  path: 'data.bin',
  directory: Directory.Documents,
  data: 'PATCHED',
  encoding: Encoding.UTF8,
  position: 100,  // Write starting at byte 100
});

Creating and Reading Directories

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

// Create a directory
await CapacitorFile.mkdir({
  path: 'my-folder/sub-folder',
  directory: Directory.Documents,
  recursive: true,
});

// Read directory contents
const result = await CapacitorFile.readdir({
  path: 'my-folder',
  directory: Directory.Documents,
});

for (const entry of result.entries) {
  console.log(`${entry.name} - ${entry.isFile ? 'file' : 'directory'}`);
}

Copying and Moving Files

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

// Copy a file
await CapacitorFile.copy({
  from: 'original.txt',
  to: 'backup/original-copy.txt',
  directory: Directory.Documents,
  toDirectory: Directory.Documents,
});

// Move/rename a file
await CapacitorFile.rename({
  from: 'old-name.txt',
  to: 'new-name.txt',
  directory: Directory.Documents,
});

Checking File Existence

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

const result = await CapacitorFile.exists({
  path: 'my-file.txt',
  directory: Directory.Documents,
});

if (result.exists) {
  console.log(`Found ${result.type}`);
}

Getting File Information

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

const stat = await CapacitorFile.stat({
  path: 'my-file.txt',
  directory: Directory.Documents,
});

console.log(`Size: ${stat.size} bytes`);
console.log(`Modified: ${new Date(stat.mtime)}`);
console.log(`Type: ${stat.type}`);

Migration from cordova-plugin-file

This plugin provides similar functionality to cordova-plugin-file with a more modern API. Here's a quick comparison:

Cordova File Plugin	This Plugin
`window.resolveLocalFileSystemURL()`	`CapacitorFile.resolveLocalFileSystemURL()`
`directoryEntry.getFile()`	`CapacitorFile.getFile()`
`directoryEntry.getDirectory()`	`CapacitorFile.getDirectory()`
`fileReader.readAsText()`	`CapacitorFile.readFile({ encoding: Encoding.UTF8 })`
`fileReader.readAsDataURL()`	`CapacitorFile.readAsDataURL()`
`fileWriter.write()`	`CapacitorFile.writeFile()`
`entry.remove()`	`CapacitorFile.deleteFile()`
`entry.moveTo()`	`CapacitorFile.move()`
`entry.copyTo()`	`CapacitorFile.copy()`
`directoryEntry.removeRecursively()`	`CapacitorFile.rmdir({ recursive: true })`
`cordova.file.dataDirectory`	`Directory.Data`
`cordova.file.documentsDirectory`	`Directory.Documents`
`cordova.file.cacheDirectory`	`Directory.Cache`

License

MPL-2.0

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌

Members	Value	Description
`Documents`	`'DOCUMENTS'`	The Documents directory (iOS) / files directory (Android) Persistent, user-visible, backed up
`Data`	`'DATA'`	The Data directory Persistent private data storage
`Library`	`'LIBRARY'`	The Library directory (iOS) / files directory (Android) Persistent but not visible to user
`Cache`	`'CACHE'`	The Cache directory Temporary cache, may be cleared by OS
`External`	`'EXTERNAL'`	External storage (Android only) SD card or external storage root
`ExternalStorage`	`'EXTERNAL_STORAGE'`	External storage data directory (Android only)
`Application`	`'APPLICATION'`	Application bundle/assets directory (read-only)