Why Does directory: "DATA" Work While Directory.DATA is Undefined in Capacitor Filesystem v7.0.0?

Capacitor
1

Hi everyone,

I’m encountering an odd behavior with the @capacitor/filesystem plugin (v7.0.0) in my Android app, and I’d love some insights from the community on why this is happening and how to align it with the “correct” approach.

Context

I’m loading the Filesystem plugin via a tag in my HTML:

html

<script src="https://unpkg.com/@capacitor/filesystem@latest/dist/filesystem.js"></script>

My app is built as a single-file JavaScript project (no bundler like Vite or Webpack) and runs natively on Android using Capacitor. I’m using the Filesystem API to save and load data, like this:

javascript

await Filesystem.writeFile({
  path: 'diario-data.json',
  data: JSON.stringify({ tema: 'padrao' }),
  directory: "DATA", // String literal
  encoding: "utf8"
});
await Filesystem.readFile({
  path: 'diario-data.json',
  directory: "DATA",
  encoding: "utf8"
});

What Works

Using directory: “DATA” (string literal) works perfectly on Android. Logs from adb logcat show successful writes and reads, and the file is saved in what I assume is the app’s private data directory (e.g., file:///data/data/com.myapp/files/diario-data.json). I get no errors, and my app behaves as expected.

The Strange Part

According to the Filesystem API docs for v7.0.0, directory should be a value from the Directory enum (e.g., Directory.DATA), not a string literal. However:

  • When I log Directory.DATA and Encoding.UTF8, they are undefined:

javascript

console.log("Directory.DATA:", Directory.DATA); // undefined
console.log("Encoding.UTF8:", Encoding.UTF8);   // undefined
console.log("Directory:", Directory);           // [object Object]
console.log("Encoding:", Encoding);            // [object Object]
  • If I try to use Directory.DATA instead of “DATA”, I get errors because it’s undefined, and the operation fails.

What I’ve Tried

  • Initially used “data” (lowercase), which failed with Invalid directory.

  • Switched to “DATA” (uppercase), which worked consistently.

  • Checked the loading — it seems to load fine (window.Capacitor.Plugins.Filesystem exists), but the enums are missing.

Questions

  1. Why does directory: “DATA” work as a string literal when the docs say it should be Directory.DATA? Is this an undocumented feature or a bug in the Android native plugin?

  2. Has anyone else faced Directory.DATA and Encoding.UTF8 being undefined when loading via ? Is this a limitation of the unpkg distribution or my setup?

  3. Why doesn’t the “correct” way (Directory.DATA) work in my case, even with v7.0.0? Shouldn’t the enums be available globally when the plugin is loaded this way?

  4. How can I make the enums work properly without switching to a full npm/bundler setup (which I’d like to avoid for now)?

Logs

Here’s a snippet from adb logcat showing it working with “DATA”:

2025-03-06 10:36:03.128  Iniciando salvamento no Filesystem...
2025-03-06 10:36:03.301  Resultado do salvamento: [object Object]
2025-03-06 10:36:03.301  Dados salvos com sucesso no Filesystem: padrao

Environment

Any insights on why this workaround works, why the enums are missing, or how to use the enums correctly in this setup would be greatly appreciated! Thanks!

P.S. I’m using AI to generate this question cause I’m Brazilian and I don’t speak english.

2

Directory.DATA is not a variable but a typescript enum type that contains the 'DATA' value.
Since you are not using typescript you have to use the actual value instead of the enum type, as you are doing.
The docs assume you are using typescript since it’s what most frameworks use nowadays.

1 Like
3

Hi Julio-ionic,

Thank you so much for your clear and insightful response! Your explanation about Directory.DATA being a TypeScript enum and the need to use the raw “DATA” value in plain JavaScript makes perfect sense. I hadn’t realized the docs were assuming a TypeScript setup, which explains why the enums were undefined in my case and why “DATA” worked as a workaround.

This completely resolves my confusion, and I can confidently stick with the string literals for now in my -based project. It’s great to know this aligns with how the native plugin interprets the values. Really appreciate you taking the time to clarify this — it’s a huge help!

Best regards,
Leandro