File System

The @vertz/desktop package provides a file system API for Vertz desktop apps running in the native webview. Every operation returns a Result<T, DesktopError> — errors are values, not exceptions.

Setup

import { fs } from '@vertz/desktop';

All functions require the desktop runtime (native webview). They return a Result error if called outside that environment.

Permissions

File system access requires permissions declared in .vertzrc:

{
  "desktop": {
    "permissions": ["fs:read", "fs:write"]
  }
}

Capability	Methods
`fs:read`	`readTextFile`, `readBinaryFile`, `readBinaryStream`, `readDir`, `stat`, `exists`
`fs:write`	`writeTextFile`, `writeBinaryFile`, `writeBinaryStream`, `createDir`, `remove`, `rename`
`fs:all`	All of the above

Text files

Reading text

const result = await fs.readTextFile('/path/to/file.txt');

if (result.ok) {
  console.log(result.data); // string (UTF-8)
} else {
  console.log(result.error.code); // DesktopErrorCode
}

Writing text

const result = await fs.writeTextFile('/path/to/file.txt', 'Hello, world!');

if (!result.ok) {
  console.error(result.error.message);
}

Binary files

Binary file operations use HTTP transport instead of JSON IPC, avoiding the 33% overhead of base64 encoding.

Reading binary data

Returns the entire file as a Uint8Array. Files larger than 2 GiB return an error suggesting readBinaryStream().

const result = await fs.readBinaryFile('/path/to/image.png');

if (result.ok) {
  const bytes: Uint8Array = result.data;
  console.log(`Read ${bytes.byteLength} bytes`);
}

Writing binary data

Writes a Uint8Array to a file. The write is atomic — data is written to a temp file first, then renamed into place for crash safety. Parent directories are created automatically.

const data = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
const result = await fs.writeBinaryFile('/path/to/output.bin', data);

if (!result.ok) {
  console.error(result.error.message);
}

Streaming binary reads

For files larger than 2 GiB or when you want to process data incrementally, use readBinaryStream(). Returns a ReadableStream<Uint8Array> — no size limit, data arrives chunk by chunk.

const result = await fs.readBinaryStream('/path/to/large-file.bin');

if (result.ok) {
  const stream: ReadableStream<Uint8Array> = result.data;
  const reader = stream.getReader();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    processChunk(value); // Uint8Array chunk
  }
}

Streaming binary writes

Write data from a ReadableStream<Uint8Array> to a file. No size limit — data flows chunk by chunk. The write is atomic (temp file + rename).

const stream = new ReadableStream<Uint8Array>({
  start(controller) {
    controller.enqueue(new Uint8Array([0x01, 0x02]));
    controller.enqueue(new Uint8Array([0x03, 0x04]));
    controller.close();
  },
});

const result = await fs.writeBinaryStream('/path/to/output.bin', stream);

Directory operations

Check existence

const result = await fs.exists('/path/to/check');
if (result.ok && result.data) {
  console.log('Exists');
}

File metadata

const result = await fs.stat('/path/to/file');
if (result.ok) {
  const { size, isFile, isDirectory, modified } = result.data;
}

List directory

const result = await fs.readDir('/path/to/dir');
if (result.ok) {
  for (const entry of result.data) {
    console.log(entry.name, entry.isFile ? 'file' : 'dir');
  }
}

Create directory

await fs.createDir('/path/to/new/dir', { recursive: true });

Remove

Removes a file or directory. Directories are removed recursively.

await fs.remove('/path/to/delete');

Rename / move

await fs.rename('/path/from.txt', '/path/to.txt');

Timeouts

All operations accept an optional timeout (milliseconds):

const result = await fs.readBinaryFile('/path/to/file', { timeout: 5000 });

if (!result.ok && result.error.code === 'TIMEOUT') {
  console.error('Read timed out after 5 seconds');
}

Error codes

Code	Meaning
`NOT_FOUND`	File or directory does not exist
`PERMISSION_DENIED`	OS-level permission denied, or IPC method not allowed
`IO_ERROR`	General I/O failure
`TIMEOUT`	Operation exceeded the specified timeout
`EXECUTION_FAILED`	Not running in the native webview

Buffered vs streaming — when to use which

	Buffered (`readBinaryFile` / `writeBinaryFile`)	Streaming (`readBinaryStream` / `writeBinaryStream`)
Size limit	2 GiB	No limit
Memory	Entire file in memory	Chunk by chunk
API	`Uint8Array`	`ReadableStream<Uint8Array>`
Best for	Images, config, small assets	Video, database dumps, large exports

Getting Started

@vertz/ui

@vertz/ui-compiler

@vertz/icons

@vertz/schema

@vertz/errors

@vertz/server

@vertz/agents

@vertz/db

@vertz/desktop

@vertz/fetch

@vertz/openapi

Deployment

Testing

Runtime

Setup

Permissions

Text files

Reading text

Writing text

Binary files

Reading binary data

Writing binary data

Streaming binary reads

Streaming binary writes

Directory operations

Check existence

File metadata

List directory

Create directory

Remove

Rename / move

Timeouts

Error codes

Buffered vs streaming — when to use which

​Setup

​Permissions

​Text files

​Reading text

​Writing text

​Binary files

​Reading binary data

​Writing binary data

​Streaming binary reads

​Streaming binary writes

​Directory operations

​Check existence

​File metadata

​List directory

​Create directory

​Remove

​Rename / move

​Timeouts

​Error codes

​Buffered vs streaming — when to use which

Setup

Permissions

Text files

Reading text

Writing text

Binary files

Reading binary data

Writing binary data

Streaming binary reads

Streaming binary writes

Directory operations

Check existence

File metadata

List directory

Create directory

Remove

Rename / move

Timeouts

Error codes

Buffered vs streaming — when to use which