Getting Started

Install

bun add @capgo/capacitor-file
bunx cap sync

Import

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

API Overview

requestFileSystem

Request a file system.

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

await CapacitorFile.requestFileSystem({} as RequestFileSystemOptions);

resolveLocalFileSystemURL

Resolve a file URL to an entry.

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

await CapacitorFile.resolveLocalFileSystemURL({} as ResolveURLOptions);

getFile

Get a file entry.

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

await CapacitorFile.getFile({} as GetFileOptions);

getDirectory

Get a directory entry.

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

await CapacitorFile.getDirectory({} as GetDirectoryOptions);

readFile

Read a file as text or base64.

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

await CapacitorFile.readFile({} as ReadFileOptions);

readAsDataURL

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

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

await CapacitorFile.readAsDataURL({} as ReadFileOptions);

writeFile

Write data to a file.

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

await CapacitorFile.writeFile({} as WriteFileOptions);

appendFile

Append data to a file.

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

await CapacitorFile.appendFile({} as WriteFileOptions);

deleteFile

Delete a file.

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

await CapacitorFile.deleteFile({} as DeleteFileOptions);

mkdir

Create a directory.

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

await CapacitorFile.mkdir({} as MkdirOptions);

rmdir

Delete a directory.

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

await CapacitorFile.rmdir({} as DeleteDirectoryOptions);

readdir

Read directory contents.

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

await CapacitorFile.readdir({} as ReaddirOptions);

stat

Get metadata about a file or directory.

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

await CapacitorFile.stat({} as StatOptions);

getMetadata

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

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

await CapacitorFile.getMetadata({} as StatOptions);

rename

Rename or move a file or directory.

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

await CapacitorFile.rename({} as RenameOptions);

move

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

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

await CapacitorFile.move({} as RenameOptions);

copy

Copy a file or directory.

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

await CapacitorFile.copy({} as CopyOptions);

exists

Check if a file or directory exists.

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

await CapacitorFile.exists({} as ExistsOptions);

getUri

Get the URI for a file.

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

await CapacitorFile.getUri({} as GetUriOptions);

truncate

Truncate a file to a specified size.

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

await CapacitorFile.truncate({} as TruncateOptions);

getDirectories

Get all known file system directories.

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

await CapacitorFile.getDirectories();

getFreeDiskSpace

Get the free disk space in bytes.

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

await CapacitorFile.getFreeDiskSpace();

checkPermissions

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.

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

await CapacitorFile.checkPermissions();

requestPermissions

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.

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

await CapacitorFile.requestPermissions();

Type Reference

RequestFileSystemOptions

Options for requesting a file system.

export interface RequestFileSystemOptions {
  /** The type of file system to request */
  type: FileSystemType;
  /** Requested size in bytes (may not be enforced on all platforms) */
  size?: number;
}

FileSystem

Represents a file system.

export interface FileSystem {
  /** The name of the file system */
  name: string;
  /** The root directory of the file system */
  root: DirectoryEntry;
}

ResolveURLOptions

Options for resolving a URL to an entry.

export interface ResolveURLOptions {
  /** The URL to resolve (file:// or cdvfile://) */
  url: string;
}

Entry

Represents a file or directory entry.

export interface Entry {
  /** True if this is a file */
  isFile: boolean;
  /** True if this is a directory */
  isDirectory: boolean;
  /** The name of the file or directory */
  name: string;
  /** The full path relative to the filesystem root */
  fullPath: string;
  /** The native file:// URI */
  nativeURL: string;
}

GetFileOptions

Options for getting a file.

export interface GetFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the file */
  options?: GetOptions;
}

FileEntry

Represents a file entry.

export interface FileEntry extends Entry {
  isFile: true;
  isDirectory: false;
}

GetDirectoryOptions

Options for getting a directory.

export interface GetDirectoryOptions {
  /** Path to the directory */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Options for creating the directory */
  options?: GetOptions;
}

DirectoryEntry

Represents a directory entry.

export interface DirectoryEntry extends Entry {
  isFile: false;
  isDirectory: true;
}

ReadFileOptions

Options for reading a file.

export interface ReadFileOptions {
  /** Path to the file */
  path: string;
  /** Base directory */
  directory?: Directory;
  /** Encoding for text files (omit for binary/base64) */
  encoding?: Encoding;
  /** Byte offset to start reading from (default: 0) */
  offset?: number;
  /** Number of bytes to read (default: read to end of file) */
  length?: number;
}

ReadFileResult

Result of reading a file.

export interface ReadFileResult {
  /** File contents as string (text) or base64 (binary) */
  data: string;
}

WriteFileOptions

Options for writing a file.

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

WriteFileResult

Result of writing a file.

export interface WriteFileResult {
  /** The URI of the written file */
  uri: string;
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.