# @capgo/capacitor-file
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
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```
Then use the following prompt:
```text
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:
```bash
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](https://github.com/Cap-go/capacitor-file-picker/) or another system picker flow instead of requesting broad photo/video permissions.
See Google's [Photo and Video Permissions policy](https://support.google.com/googleplay/android-developer/answer/14115180) for the current review requirements.
## API
* [`requestFileSystem(...)`](#requestfilesystem)
* [`resolveLocalFileSystemURL(...)`](#resolvelocalfilesystemurl)
* [`getFile(...)`](#getfile)
* [`getDirectory(...)`](#getdirectory)
* [`readFile(...)`](#readfile)
* [`readAsDataURL(...)`](#readasdataurl)
* [`writeFile(...)`](#writefile)
* [`appendFile(...)`](#appendfile)
* [`deleteFile(...)`](#deletefile)
* [`mkdir(...)`](#mkdir)
* [`rmdir(...)`](#rmdir)
* [`readdir(...)`](#readdir)
* [`stat(...)`](#stat)
* [`getMetadata(...)`](#getmetadata)
* [`rename(...)`](#rename)
* [`move(...)`](#move)
* [`copy(...)`](#copy)
* [`exists(...)`](#exists)
* [`getUri(...)`](#geturi)
* [`truncate(...)`](#truncate)
* [`getDirectories()`](#getdirectories)
* [`getFreeDiskSpace()`](#getfreediskspace)
* [`addListener('readProgress', ...)`](#addlistenerreadprogress-)
* [`addListener('writeProgress', ...)`](#addlistenerwriteprogress-)
* [`removeAllListeners()`](#removealllisteners)
* [`getPluginVersion()`](#getpluginversion)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions(...)`](#requestpermissions)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)
Capacitor File Plugin
Implements file system operations similar to the Cordova File plugin
### requestFileSystem(...)
```typescript
requestFileSystem(options: RequestFileSystemOptions) => Promise
```
Request a file system.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------------- | ----------------------------- |
| **`options`** | RequestFileSystemOptions | - File system request options |
**Returns:** Promise<FileSystem>
--------------------
### resolveLocalFileSystemURL(...)
```typescript
resolveLocalFileSystemURL(options: ResolveURLOptions) => Promise
```
Resolve a file URL to an entry.
| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ---------------- |
| **`options`** | ResolveURLOptions | - URL to resolve |
**Returns:** Promise<Entry>
--------------------
### getFile(...)
```typescript
getFile(options: GetFileOptions) => Promise
```
Get a file entry.
| Param | Type | Description |
| ------------- | --------------------------------------------------------- | ----------------------- |
| **`options`** | GetFileOptions | - File path and options |
**Returns:** Promise<FileEntry>
--------------------
### getDirectory(...)
```typescript
getDirectory(options: GetDirectoryOptions) => Promise
```
Get a directory entry.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
| **`options`** | GetDirectoryOptions | - Directory path and options |
**Returns:** Promise<DirectoryEntry>
--------------------
### readFile(...)
```typescript
readFile(options: ReadFileOptions) => Promise
```
Read a file as text or base64.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------- | -------------- |
| **`options`** | ReadFileOptions | - Read options |
**Returns:** Promise<ReadFileResult>
--------------------
### readAsDataURL(...)
```typescript
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; }>
--------------------
### writeFile(...)
```typescript
writeFile(options: WriteFileOptions) => Promise
```
Write data to a file.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------- | --------------- |
| **`options`** | WriteFileOptions | - Write options |
**Returns:** Promise<WriteFileResult>
--------------------
### appendFile(...)
```typescript
appendFile(options: WriteFileOptions) => Promise
```
Append data to a file.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------- | ------------------------------------------ |
| **`options`** | WriteFileOptions | - Write options (append is forced to true) |
**Returns:** Promise<WriteFileResult>
--------------------
### deleteFile(...)
```typescript
deleteFile(options: DeleteFileOptions) => Promise
```
Delete a file.
| Param | Type | Description |
| ------------- | --------------------------------------------------------------- | ---------------- |
| **`options`** | DeleteFileOptions | - Delete options |
--------------------
### mkdir(...)
```typescript
mkdir(options: MkdirOptions) => Promise
```
Create a directory.
| Param | Type | Description |
| ------------- | ----------------------------------------------------- | ----------------------------------------------------- |
| **`options`** | MkdirOptions | - Directory creation options |
--------------------
### rmdir(...)
```typescript
rmdir(options: DeleteDirectoryOptions) => Promise
```
Delete a directory.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------------- | ---------------- |
| **`options`** | DeleteDirectoryOptions | - Delete options |
--------------------
### readdir(...)
```typescript
readdir(options: ReaddirOptions) => Promise
```
Read directory contents.
| Param | Type | Description |
| ------------- | --------------------------------------------------------- | -------------- |
| **`options`** | ReaddirOptions | - Read options |
**Returns:** Promise<ReaddirResult>
--------------------
### stat(...)
```typescript
stat(options: StatOptions) => Promise
```
Get metadata about a file or directory.
| Param | Type | Description |
| ------------- | --------------------------------------------------- | -------------- |
| **`options`** | StatOptions | - Stat options |
**Returns:** Promise<StatResult>
--------------------
### getMetadata(...)
```typescript
getMetadata(options: StatOptions) => Promise
```
Get metadata about a file or directory.
Alias for stat().
| Param | Type | Description |
| ------------- | --------------------------------------------------- | -------------- |
| **`options`** | StatOptions | - Stat options |
**Returns:** Promise<Metadata>
--------------------
### rename(...)
```typescript
rename(options: RenameOptions) => Promise
```
Rename or move a file or directory.
| Param | Type | Description |
| ------------- | ------------------------------------------------------- | ---------------- |
| **`options`** | RenameOptions | - Rename options |
--------------------
### move(...)
```typescript
move(options: RenameOptions) => Promise
```
Move a file or directory.
Alias for rename().
| Param | Type | Description |
| ------------- | ------------------------------------------------------- | -------------- |
| **`options`** | RenameOptions | - Move options |
--------------------
### copy(...)
```typescript
copy(options: CopyOptions) => Promise
```
Copy a file or directory.
| Param | Type | Description |
| ------------- | --------------------------------------------------- | -------------- |
| **`options`** | CopyOptions | - Copy options |
**Returns:** Promise<CopyResult>
--------------------
### exists(...)
```typescript
exists(options: ExistsOptions) => Promise
```
Check if a file or directory exists.
| Param | Type | Description |
| ------------- | ------------------------------------------------------- | --------------- |
| **`options`** | ExistsOptions | - Check options |
**Returns:** Promise<ExistsResult>
--------------------
### getUri(...)
```typescript
getUri(options: GetUriOptions) => Promise
```
Get the URI for a file.
| Param | Type | Description |
| ------------- | ------------------------------------------------------- | ------------- |
| **`options`** | GetUriOptions | - URI options |
**Returns:** Promise<GetUriResult>
--------------------
### truncate(...)
```typescript
truncate(options: TruncateOptions) => Promise
```
Truncate a file to a specified size.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------- | ------------------ |
| **`options`** | TruncateOptions | - Truncate options |
--------------------
### getDirectories()
```typescript
getDirectories() => Promise
```
Get all known file system directories.
**Returns:** Promise<FileDirectories>
--------------------
### getFreeDiskSpace()
```typescript
getFreeDiskSpace() => Promise<{ free: number; }>
```
Get the free disk space in bytes.
**Returns:** Promise<{ free: number; }>
--------------------
### addListener('readProgress', ...)
```typescript
addListener(eventName: 'readProgress', listenerFunc: (progress: ProgressEvent) => void) => Promise
```
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', ...)
```typescript
addListener(eventName: 'writeProgress', listenerFunc: (progress: ProgressEvent) => void) => Promise
```
Listen for write progress events.
| Param | Type | Description |
| ------------------ | ------------------------------------------------------------------------------ | ------------------------------------- |
| **`eventName`** | 'writeProgress' | - Must be 'writeProgress' |
| **`listenerFunc`** | (progress: ProgressEvent) => void | - Callback receiving progress updates |
**Returns:** Promise<PluginListenerHandle>
--------------------
### removeAllListeners()
```typescript
removeAllListeners() => Promise
```
Remove all event listeners.
--------------------
### getPluginVersion()
```typescript
getPluginVersion() => Promise<{ version: string; }>
```
Get the plugin version.
**Returns:** Promise<{ version: string; }>
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise
```
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(...)
```typescript
requestPermissions(options?: PermissionRequestOptions | undefined) => Promise
```
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 | |
### Type Aliases
#### PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
### Enums
#### FileSystemType
| Members | Value |
| ---------------- | -------------- |
| **`TEMPORARY`** | 0 |
| **`PERSISTENT`** | 1 |
#### Directory
| 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) |
#### Encoding
| Members | Value |
| ----------- | -------------------- |
| **`UTF8`** | 'utf8' |
| **`ASCII`** | 'ascii' |
| **`UTF16`** | 'utf16' |
## Usage Examples
### Reading a File
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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