Capacitor Filesystem

@capacitor/filesystem is the official Capacitor plugin that gives hybrid mobile and web apps a single, Promise-based API for working with files on the device. Instead of hand-rolling separate native file I/O for iOS and Android and a browser fallback for web, developers call one consistent JavaScript API — readFile, writeFile, appendFile, mkdir, rmdir, readdir, stat, rename, copy — and the plugin routes each call to Swift on iOS, Kotlin/Java on Android, or an IndexedDB-backed implementation in the browser.

The plugin scopes file operations to well-known Directory locations (Documents, Data, Cache, Library, External, ExternalStorage, Temporary) so apps don’t need to hardcode platform-specific paths, and it handles base64/UTF-8 encoding, chunked reads for large files, and Android runtime storage permissions. It is maintained by the Ionic/Capacitor team as one of the official first-party Capacitor plugins alongside Camera, Geolocation, and Preferences.

What You Get

• A unified readFile/writeFile/appendFile/deleteFile API that works identically across iOS, Android, and web
• Directory-scoped storage locations (Documents, Data, Cache, Library, External, ExternalStorage, Temporary) that map to the correct platform-native path automatically
• Directory operations — mkdir, rmdir, readdir, stat, rename, copy — for full filesystem management, not just single-file I/O
• Chunked file reading (readFileInChunks) for streaming large files without loading them entirely into memory
• Built-in Android runtime permission handling (checkPermissions/requestPermissions) for storage access
• A web fallback backed by IndexedDB so the same code runs unmodified in a browser during development or on a PWA build

Common Use Cases

• Persisting user-generated content (notes, drawings, downloaded documents) to app-scoped storage that survives app restarts
• Caching downloaded assets (images, PDFs, offline data bundles) in the Cache or Temporary directory for offline-first apps
• Reading and writing files shared with other apps via the Documents or ExternalStorage directory on Android
• Converting between file paths and base64/UTF-8 content when passing files to and from other Capacitor plugins like Camera or File Transfer

Under The Hood

Architecture The plugin follows Capacitor’s standard three-implementation pattern: a shared TypeScript surface (src/definitions.ts) declares the FilesystemPlugin interface and all option/result types, which is then implemented natively per platform. src/web.ts backs the browser implementation with IndexedDB (a versioned object store keyed by path), reconstructing directory semantics that don’t natively exist on the web. The iOS implementation (ios/Sources/FilesystemPlugin) separates concerns into FilesystemOperation, FilesystemOperationExecutor, and FilesystemLocationResolver, cleanly isolating path resolution from the actual read/write execution, with FilesystemPlugin.swift as the Capacitor bridge entry point. Android mirrors this with FilesystemPlugin.kt plus dedicated FilesystemMethodOptions/FilesystemMethodResults classes for typed marshaling to/from the JS bridge, and a LegacyFilesystemImplementation.kt retained for backward compatibility with pre-Directory-enum call patterns on both platforms.

Tech Stack The JS/TS layer targets TypeScript ~5.9 and depends on @capacitor/core (>=8.0.0 peer dependency) and @capacitor/synapse for cross-context bridging; it builds via tsc plus Rollup into CJS, ESM, and UMD bundles, with @capacitor/docgen auto-generating the README API reference from JSDoc comments. Android is Kotlin-first, building against the shared android/build.gradle Capacitor plugin conventions. iOS uses Swift Package Manager (Package.swift) as the primary distribution mechanism, with a CapacitorFilesystem.podspec kept for CocoaPods consumers. Releases are fully automated via semantic-release with conventional commits, changelog generation, and coordinated npm + CocoaPods publishing.

Code Quality The TypeScript source is disciplined and small (about 1,500 lines across definitions.ts, web.ts, and index.ts), consistently typed with no any escapes, and every public method carries an @since JSDoc tag documenting the version it was introduced in — useful for consumers tracking API stability across major versions. Native-side testing exists but is thin: iOS has a dedicated FilesystemPluginTests.swift suite, while Android’s test directories mostly still contain Capacitor’s boilerplate ExampleUnitTest scaffolding rather than plugin-specific coverage. Error handling is centralized through FilesystemErrors.kt (Android) and FilesystemError.swift (iOS), giving callers a consistent set of named error codes across platforms instead of raw native exceptions.

API Design The API deliberately mirrors Node’s fs module (readFile, writeFile, appendFile, mkdir, rmdir, readdir, rename, copy), which makes it immediately familiar to any JavaScript developer and minimizes the learning curve documented in the README. The Directory enum removes the need to hand-manage platform-specific absolute paths, and options objects are consistently typed per method. The main friction point is base64 vs UTF-8 encoding: callers must explicitly choose an Encoding value or omit it for binary/base64 data, a distinction that isn’t always obvious from the method signature alone and is a common source of support questions in the plugin’s issue tracker.