From 78dc1634a3d0a40976f7a04f12e7debbf161b457 Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Fri, 23 Jan 2026 17:09:07 +0000 Subject: [PATCH 1/2] docs: Better document writing binary data --- README.md | 10 ++++++ packages/capacitor-plugin/README.md | 36 +++++++++++++------- packages/capacitor-plugin/src/definitions.ts | 12 ++++--- 3 files changed, 40 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index e70ff1f..8457a53 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,16 @@ const readFilePath = async () => { console.log("data:", contents); }; + +const appendBinaryData = async () => { + // Here's an example of appending binary data, which should be sent to the plugin + // as base64 encoded, and without providing any `Encoding` + await Filesystem.appendFile({ + path: "file.bin", + directory: Directory.Cache, + data: "VGhpcyBpcyBtZWFudCB0byByZXByZXNlbnQgYSBCaW5hcnkgRGF0YSBleGFtcGxlIGVuY29kZWQgaW4gQmFzZTY0Lg==" + }); +}; ``` ## API diff --git a/packages/capacitor-plugin/README.md b/packages/capacitor-plugin/README.md index 9a0c910..1333a15 100644 --- a/packages/capacitor-plugin/README.md +++ b/packages/capacitor-plugin/README.md @@ -171,6 +171,16 @@ const readFilePath = async () => { console.log("data:", contents); }; + +const appendBinaryData = async () => { + // Here's an example of appending binary data, which should be sent to the plugin + // as base64 encoded, and without providing any `Encoding`. + await Filesystem.appendFile({ + path: "file.bin", + directory: Directory.Cache, + data: "VGhpcyBpcyBtZWFudCB0byByZXByZXNlbnQgYSBCaW5hcnkgRGF0YSBleGFtcGxlIGVuY29kZWQgaW4gQmFzZTY0Lg==" + }); +}; ``` ## API @@ -566,23 +576,23 @@ We recommend using the @capacitor/file-transfer plugin instead, in conjunction w #### WriteFileOptions -| Prop | Type | Description | Default | Since | -| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | -| **`path`** | string | The path of the file to write | | 1.0.0 | -| **`data`** | string \| Blob | The data to write Note: Blob data is only supported on Web. | | 1.0.0 | -| **`directory`** | Directory | The `Directory` to store the file in | | 1.0.0 | -| **`encoding`** | Encoding | The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string | | 1.0.0 | -| **`recursive`** | boolean | Whether to create any missing parent directories. | false | 1.0.0 | +| Prop | Type | Description | Default | Since | +| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | +| **`path`** | string | The path of the file to write | | 1.0.0 | +| **`data`** | string \| Blob | The data to write Note: Blob data is only supported on Web. | | 1.0.0 | +| **`directory`** | Directory | The `Directory` to store the file in | | 1.0.0 | +| **`encoding`** | Encoding | The encoding to write the file in. If not provided, binary data will be written. For this, you should provide data as base64 encoded, so that the plugin can decode it before writing to disk. Pass Encoding.UTF8 to write data as string | | 1.0.0 | +| **`recursive`** | boolean | Whether to create any missing parent directories. | false | 1.0.0 | #### AppendFileOptions -| Prop | Type | Description | Since | -| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -| **`path`** | string | The path of the file to append | 1.0.0 | -| **`data`** | string | The data to write | 1.0.0 | -| **`directory`** | Directory | The `Directory` to store the file in | 1.0.0 | -| **`encoding`** | Encoding | The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string | 1.0.0 | +| Prop | Type | Description | Since | +| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| **`path`** | string | The path of the file to append | 1.0.0 | +| **`data`** | string | The data to append | 1.0.0 | +| **`directory`** | Directory | The `Directory` to store the file in | 1.0.0 | +| **`encoding`** | Encoding | The encoding to append to the file. If not provided, binary data will be appended. For this, you should provide data as base64 encoded, so that the plugin can decode it before writing to disk. Pass Encoding.UTF8 to write data as string | 1.0.0 | #### DeleteFileOptions diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index 72e4141..45d49d4 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/packages/capacitor-plugin/src/definitions.ts @@ -154,8 +154,9 @@ export interface WriteFileOptions { directory?: Directory; /** - * The encoding to write the file in. If not provided, data - * is written as base64 encoded. + * The encoding to write the file in. + * If not provided, binary data will be written. For this, you should provide data as base64 encoded, + * so that the plugin can decode it before writing to disk. * * Pass Encoding.UTF8 to write data as string * @@ -181,7 +182,7 @@ export interface AppendFileOptions { path: string; /** - * The data to write + * The data to append * * @since 1.0.0 */ @@ -195,8 +196,9 @@ export interface AppendFileOptions { directory?: Directory; /** - * The encoding to write the file in. If not provided, data - * is written as base64 encoded. + * The encoding to append to the file. + * If not provided, binary data will be appended. For this, you should provide data as base64 encoded, + * so that the plugin can decode it before writing to disk. * * Pass Encoding.UTF8 to write data as string * From a0482bc3e63d4d4dee6ba749a33e23a36bd5ec0f Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 10:08:34 +0000 Subject: [PATCH 2/2] docs: Make explicit that base64 is mandatory with no encoding --- packages/capacitor-plugin/README.md | 26 ++++++++++---------- packages/capacitor-plugin/src/definitions.ts | 6 +++-- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/packages/capacitor-plugin/README.md b/packages/capacitor-plugin/README.md index 1333a15..90c91df 100644 --- a/packages/capacitor-plugin/README.md +++ b/packages/capacitor-plugin/README.md @@ -576,23 +576,23 @@ We recommend using the @capacitor/file-transfer plugin instead, in conjunction w #### WriteFileOptions -| Prop | Type | Description | Default | Since | -| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | -| **`path`** | string | The path of the file to write | | 1.0.0 | -| **`data`** | string \| Blob | The data to write Note: Blob data is only supported on Web. | | 1.0.0 | -| **`directory`** | Directory | The `Directory` to store the file in | | 1.0.0 | -| **`encoding`** | Encoding | The encoding to write the file in. If not provided, binary data will be written. For this, you should provide data as base64 encoded, so that the plugin can decode it before writing to disk. Pass Encoding.UTF8 to write data as string | | 1.0.0 | -| **`recursive`** | boolean | Whether to create any missing parent directories. | false | 1.0.0 | +| Prop | Type | Description | Default | Since | +| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ----- | +| **`path`** | string | The path of the file to write | | 1.0.0 | +| **`data`** | string \| Blob | The data to write Note: Blob data is only supported on Web. | | 1.0.0 | +| **`directory`** | Directory | The `Directory` to store the file in | | 1.0.0 | +| **`encoding`** | Encoding | The encoding to write the file in. If not provided, binary data will be written. For this, you must provide data as base64 encoded, so that the plugin can decode it before writing to disk. If you do not provide encoding and use non-base64 data, an error will be thrown. Pass Encoding.UTF8 to write data as string | | 1.0.0 | +| **`recursive`** | boolean | Whether to create any missing parent directories. | false | 1.0.0 | #### AppendFileOptions -| Prop | Type | Description | Since | -| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -| **`path`** | string | The path of the file to append | 1.0.0 | -| **`data`** | string | The data to append | 1.0.0 | -| **`directory`** | Directory | The `Directory` to store the file in | 1.0.0 | -| **`encoding`** | Encoding | The encoding to append to the file. If not provided, binary data will be appended. For this, you should provide data as base64 encoded, so that the plugin can decode it before writing to disk. Pass Encoding.UTF8 to write data as string | 1.0.0 | +| Prop | Type | Description | Since | +| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | +| **`path`** | string | The path of the file to append | 1.0.0 | +| **`data`** | string | The data to append | 1.0.0 | +| **`directory`** | Directory | The `Directory` to store the file in | 1.0.0 | +| **`encoding`** | Encoding | The encoding to append to the file. If not provided, binary data will be appended. For this, you must provide data as base64 encoded, so that the plugin can decode it before writing to disk. If you do not provide encoding and use non-base64 data, an error will be thrown. Pass Encoding.UTF8 to write data as string | 1.0.0 | #### DeleteFileOptions diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index 45d49d4..bfe98f8 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/packages/capacitor-plugin/src/definitions.ts @@ -155,8 +155,9 @@ export interface WriteFileOptions { /** * The encoding to write the file in. - * If not provided, binary data will be written. For this, you should provide data as base64 encoded, + * If not provided, binary data will be written. For this, you must provide data as base64 encoded, * so that the plugin can decode it before writing to disk. + * If you do not provide encoding and use non-base64 data, an error will be thrown. * * Pass Encoding.UTF8 to write data as string * @@ -197,8 +198,9 @@ export interface AppendFileOptions { /** * The encoding to append to the file. - * If not provided, binary data will be appended. For this, you should provide data as base64 encoded, + * If not provided, binary data will be appended. For this, you must provide data as base64 encoded, * so that the plugin can decode it before writing to disk. + * If you do not provide encoding and use non-base64 data, an error will be thrown. * * Pass Encoding.UTF8 to write data as string *