Methods for checking if file/directory exists

[kstruempf]

Feature Request

Plugin

@capacitor/filesystem

Description

Please add two first-class helper methods—

• exists() – returns true | false for a file
• dirExists() – returns true | false for a directory

Today developers have to call Filesystem.stat() inside a try / catch, then inspect the thrown error to decide whether the path is missing or some other I/O problem. The highest‑voted answer on Stack Overflow (https://stackoverflow.com/questions/59434175/capacitor-check-if-file-exists) shows exactly this pattern and even resorts to string‑matching the message "File does not exist" (or "Entry does not exist" on Web) to tell the two cases apart.

This approach is:

• Boilerplate‑heavy – every existence check needs a wrapper.
• Error‑prone – messages differ between platforms (and can be localized by the OS language), so equality checks might break for non‑English users.
• Non‑obvious – newcomers search the docs, find nothing, then land on the Stack Overflow thread.

Adding dedicated helpers would remove the need for fragile error‑string matching and make the common “does this file/folder exist?” question a single‑line call.

Platform(s)

• iOS
• Android
• Web (PWA)

Preferred Solution

Option A

Expose two promise‑based methods on the public API:

// File
exists(options: { path: string; directory?: Directory }): Promise<{ exists: boolean }>;

// Directory
dirExists(options: { path: string; directory?: Directory }): Promise<{ exists: boolean }>;

Option B

Expose a single promise‑based methods on the public API, that checks if either a file or directory exists:

// File or Directory
exists(options: { path: string; directory?: Directory }): Promise<{ exists: boolean }>;

---

• Return shape mirrors other plugin patterns ({ exists: boolean }).
• Internally call the native file‑system’s “stat”/“access” function and resolve without throwing.
• No breaking changes—stat() keeps its current behaviour.

Alternatives

1. try { await stat() } catch { … } – verbose, incurs bridge overhead, relies on untranslated error strings.
2. readdir() + manual search – O(n) and still requires error handling when the parent directory is absent.
3. Third‑party utility wrappers – every project reinvents the same helper.

Additional Context

• Long‑standing Stack Overflow thread showing the current pain point: https://stackoverflow.com/questions/59434175/capacitor-check-if-file-exists
• Similar requests have popped up in GitHub issues over the years, demonstrating recurring demand.
• Other ecosystems (Node fs, Web FileSystemAccess, Kotlin File.exists(), Swift FileManager.fileExists(atPath:)) all expose an explicit “exists” helper—Capacitor should too for parity.

Implementing exists() / dirExists() would eliminate try/catch boilerplate, work consistently across locales, and smooth out a very common developer workflow.

[kstruempf]

@OS-pedrogustavobilro do you have any preferences on the interface design (Option A or Option B)?
We have been thinking about implementing this in the next couple of weeks.

[OS-pedrogustavobilro]

Hey @kstruempf, in my opinion Option B is preferable, as natively the check for something existing should not depend on it being a file or directory.

Thanks for your interest in implementing, keep in mind that the native code is split in native libraries for Android and iOS, so it can involve multiple PRs.