HELP : `vault.adapter.write()` VS `vault.modifyBinary()` for working with custom files to store json data

Tu2_atmanand · April 23, 2026, 6:56am

Confusion

The question I am asking here is to make things clear about the various APIs provided by Obsidian to work with custom files (non-markdown/non0text files) and their performance differences. I want to decide which API I should be using to avoid any future limitations and bugs for my use-case.

Right now, we have the following APIs in Obsidian :

vault.adapter.write() : The JSDocs says, its for plaintext files. But, it does work for json data for custom files (for example, files with .taskboard file extension)
vault.adapter.writeBinary() : I havent tried this, but it should work same for my usecase.
vault.modifyBinary() / vault.createBinary() : I have tried this, this works same as in the first API for me.

My question is, when I was using the 3rd approach earlier, I had to do some extra encoding/decoding operations for the data to get stored properly in my file. (Unless, if there was a simpler solution, I would love to know). And, I went with this approach from the start because, it makes sense, since I am working with custom file extension, with json format.

But, just to try it out, I have now used the 1st approach. And, I havent noticed any difference, either the way the data is stored (when I opened the .taskboard file in notepad editor) or I guess with the size of the file.

I have created this post, to understand the difference between the above three APIs I have mentioned, so I know what to expect from them and I can choose the right one for my usecase.

My use-case

I am not looking for storing the data exactly in the json format. Right now, with both the approaches, I have used, the data is stored like a single contineous string (JSON.stringify()). Which is fine with me, as I am not expecting users to open that file and edit anything. But, if I am able to see the content, then I can simply copy paste it inside a JSON editor (VS Code) and that will automatically format it in a JSON format, in situations when I want to debug the content, etc.

So, right now both the approaches are giving me the expected results. You may also refer the code below and let me know if there is any improvements I can do to handle any future bug from happening before-hand.

Example

When I was using the 3rd approach :

github.com/tu2-atmanand/Task-Board

src/managers/TaskBoardFileManager.ts

e8ff4bb02


      
          	async saveBoardToDiskEncoded(
          		filePath: string,
          		boardData: Board,
          	): Promise<boolean> {
          		try {
          			// Check if file exists, if not create it
          			const fileExists = await this.app.vault.adapter.exists(filePath);
          
          			// Convert board data to JSON string, then to Uint8Array for binary storage
          			const jsonString = JSON.stringify(boardData);
          			const uint8Array = new TextEncoder().encode(jsonString);
          			const arrayBuffer = uint8Array.buffer.slice(
          				uint8Array.byteOffset,
          				uint8Array.byteOffset + uint8Array.byteLength,
          			);
          
          			if (!fileExists) {
          				// Create new file with binary data
          				await this.app.vault.createBinary(
          					filePath,

This file has been truncated. show original

After I moved to the 1st approach :

github.com/tu2-atmanand/Task-Board

src/managers/TaskBoardFileManager.ts

e8ff4bb02


      
          	async saveBoardToDisk(
          		filePath: string,
          		boardData: Board,
          	): Promise<boolean> {
          		try {
          			// Convert board data to JSON string
          			const jsonString = JSON.stringify(boardData);
          			await this.app.vault.adapter.write(filePath, jsonString);
          
          			return true;
          		} catch (error) {
          			console.error(`Error saving board to file ${filePath}:`, error);
          			return false;
          		}
          	}

Tu2_atmanand · April 23, 2026, 7:14am

This concern was also raised after looking at the Excalidraw plugin code :

github.com/zsviczian/obsidian-excalidraw-plugin

src/utils/fileUtils.ts

fb21d5516


      
          export async function createOrOverwriteFile(app: App, path: string, content: string | ArrayBuffer | Blob): Promise<TFile> {

            const {folderpath} = splitFolderAndFilename(path);

            if(folderpath) {

              await checkAndCreateFolder(folderpath);

            }

            const file = app.vault.getAbstractFileByPath(normalizePath(path));

            if (content instanceof Blob) {

              content = await content.arrayBuffer();

            }

            if(content instanceof ArrayBuffer) {

              if(file && file instanceof TFile) {

                await app.vault.modifyBinary(file, content);

                return file;

              } else {

                return await app.vault.createBinary(path, content);

              }

            }

          

            if (file && file instanceof TFile) {

              await app.vault.modify(file, content);

This file has been truncated. show original

Excalidraw plugin also uses the third approach. And, I am using this plugin as inspiration, as I am doing quite a similar things. It might not be that much of data as a .excalidraw file. But still want to make sure, if my .taskboard file size grows huge, will there be any problems.

I wanted to specifically ask this question to Excalidraw plugin devs, but I am expecting here to get some more knowledge on this.