@capgo/capacitor-file

Work with the device file system from your Capacitor app using an API compatible with cordova-plugin-file. Read, write, copy and move files and folders on iOS, Android and the web.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-file in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-file to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Read and write: readFile(), readAsDataURL(), writeFile(), appendFile() and truncate().
• Files and folders: mkdir(), rmdir(), readdir(), copy(), move(), rename() and deleteFile().
• Metadata: stat(), exists(), getUri() and getFreeDiskSpace().
• Cordova compatible: requestFileSystem(), resolveLocalFileSystemURL(), getFile() and getDirectory() ease migration from cordova-plugin-file.
• Permissions: checkPermissions() and requestPermissions() for storage access.
• Platforms: iOS, Android and Web. Web keeps the core file operations in browser storage.

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

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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-file` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-file
npx cap sync

Android media permissions and Google Play review

On Android 13+ this plugin can request broad media permissions such as READ_MEDIA_IMAGES and READ_MEDIA_VIDEO when you call requestPermissions() for access outside your app's private directories.

Google Play only allows these photo and video permissions when access is directly related to your app's core purpose and requires persistent or frequent access to photos or videos in shared storage. If your app only needs one-time or infrequent media access, such as importing a profile picture, selecting an attachment, or choosing a file to upload, Google expects you to use a system picker instead.

Before publishing an app that requests these permissions:

• Make sure photo or video library access is part of your app's core functionality.
• Be ready to justify the permission usage in Play Console review.
• Remove broad media permissions if the app can work with user-selected files only.

If Google Play review rejects the app with a message like Photo and Video Permissions policy: Permission use is not directly related to your app's core purpose, use @capgo/capacitor-file-picker or another system picker flow instead of requesting broad photo/video permissions.

See Google's Photo and Video Permissions policy for the current review requirements.

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

requestFileSystem(...)

requestFileSystem(options: RequestFileSystemOptions) => Promise<FileSystem>

Request a file system.

Returns: Promise<FileSystem>

resolveLocalFileSystemURL(...)

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

Resolve a file URL to an entry.

Returns: Promise<Entry>

getFile(...)

getFile(options: GetFileOptions) => Promise<FileEntry>

Get a file entry.

Returns: Promise<FileEntry>

getDirectory(...)

getDirectory(options: GetDirectoryOptions) => Promise<DirectoryEntry>

Get a directory entry.

Returns: Promise<DirectoryEntry>

readFile(...)

readFile(options: ReadFileOptions) => Promise<ReadFileResult>

Read a file as text or base64.

Returns: Promise<ReadFileResult>

readAsDataURL(...)

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

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

Returns: Promise<{ data: string; }>

writeFile(...)

writeFile(options: WriteFileOptions) => Promise<WriteFileResult>

Write data to a file.

Returns: Promise<WriteFileResult>

appendFile(...)

appendFile(options: WriteFileOptions) => Promise<WriteFileResult>

Append data to a file.

Returns: Promise<WriteFileResult>

deleteFile(...)

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

Delete a file.

mkdir(...)

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

Create a directory.

rmdir(...)

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

Delete a directory.

readdir(...)

readdir(options: ReaddirOptions) => Promise<ReaddirResult>

Read directory contents.

Returns: Promise<ReaddirResult>

stat(...)

stat(options: StatOptions) => Promise<StatResult>

Get metadata about a file or directory.

Returns: Promise<StatResult>

getMetadata(...)

getMetadata(options: StatOptions) => Promise<Metadata>

Get metadata about a file or directory. Alias for stat().

Returns: Promise<Metadata>

rename(...)

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

Rename or move a file or directory.

move(...)

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

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

copy(...)

copy(options: CopyOptions) => Promise<CopyResult>

Copy a file or directory.

Returns: Promise<CopyResult>

exists(...)

exists(options: ExistsOptions) => Promise<ExistsResult>

Check if a file or directory exists.

Returns: Promise<ExistsResult>

getUri(...)

getUri(options: GetUriOptions) => Promise<GetUriResult>

Get the URI for a file.

Returns: Promise<GetUriResult>

truncate(...)

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

Truncate a file to a specified size.

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.

Returns: Promise<PluginListenerHandle>

addListener('writeProgress', ...)

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

Listen for write progress events.

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all event listeners.

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.

Returns: Promise<FilePermissionStatus>

Interfaces

FileSystem

Represents a file system

DirectoryEntry

Represents a directory entry

RequestFileSystemOptions

Options for requesting a file system

Entry

Represents a file or directory entry

ResolveURLOptions

Options for resolving a URL to an entry

FileEntry

Represents a file entry

GetFileOptions

Options for getting a file

GetOptions

Options for creating or getting files/directories

GetDirectoryOptions

Options for getting a directory

ReadFileResult

Result of reading a file

ReadFileOptions

Options for reading a file

WriteFileResult

Result of writing a file

WriteFileOptions

Options for writing a file

DeleteFileOptions

Options for deleting a file or directory

MkdirOptions

Options for creating a directory

DeleteDirectoryOptions

Options for deleting a directory recursively

ReaddirResult

Result of reading a directory

ReaddirOptions

Options for reading a directory

StatResult

Result of getting file/directory information

StatOptions

Options for getting file information

Metadata

Represents metadata about a file or directory

RenameOptions

Options for renaming/moving a file or directory

CopyResult

Result of copy operation

CopyOptions

Options for copying a file or directory

ExistsResult

Result of existence check

ExistsOptions

Options for checking if a file or directory exists

GetUriResult

Result of getting a URI

GetUriOptions

Options for getting the URI of a file

TruncateOptions

Options for truncating a file

FileDirectories

Known file system directories exposed by the plugin

PluginListenerHandle

ProgressEvent

Progress event for file operations

FilePermissionStatus

Permission status for file operations

PermissionRequestOptions

Options for requesting permissions

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

FileSystemType

Directory

Encoding

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:

License

MPL-2.0