File System

import { Callout } from 'fumadocs-ui/components/callout';

Reads and writes files natively on the device.

Overview

The File System API provides a unified interface for accessing the native Application Documents and Cache directories. It bypasses browser sandbox limitations to store files, persist configurations, and manage offline assets. Use it to save media files, generate reports, or keep data safe from browser cache clears.

Enterprise React Example

In a Next.js/React application, you might use the File System plugin to manage offline configurations.

import React, { useState, useEffect, useCallback } from 'react';

interface AppConfig {
  theme: 'light' | 'dark';
  offlineMode: boolean;
}

export default function ConfigManager() {
  const [config, setConfig] = useState<AppConfig | null>(null);
  const [error, setError] = useState<string | null>(null);

  const loadConfig = useCallback(async () => {
    try {
      const dir = await window.easycord.fs.getAppDirectory();
      const file = await window.easycord.fs.readTextFile(`${dir.path}/config.json`);
      setConfig(JSON.parse(file.contents));
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error');
    }
  }, []);

  const saveConfig = async (newConfig: AppConfig) => {
    try {
      const dir = await window.easycord.fs.getAppDirectory();
      await window.easycord.fs.writeTextFile(
        `${dir.path}/config.json`,
        JSON.stringify(newConfig, null, 2)
      );
      setConfig(newConfig);
    } catch (err) {
      console.error("Failed to save config", err);
    }
  };

  useEffect(() => {
    loadConfig();
  }, [loadConfig]);

  if (error) return <div className="text-red-500">Error: {error}</div>;
  if (!config) return <div>Loading configuration...</div>;

  return (
    <div className="p-4 border rounded">
      <h3>App Configuration</h3>
      <p>Theme: {config.theme}</p>
      <button onClick={() => saveConfig({ ...config, theme: config.theme === 'light' ? 'dark' : 'light' })}>
        Toggle Theme
      </button>
    </div>
  );
}

API Reference

`getAppDirectory()`

Gets the absolute path to the app's secure sandboxed Documents directory.

Returns: Promise<{path: string}>

readTextFile()

Reads the contents of a file as a UTF-8 string.

Android	iOS	Web	Desktop
Yes	Yes	No	No

Parameters

Name	Type	Required	Description
path	string	Yes	The absolute path to the file.

Returns

Promise<{ success: boolean; contents: string }>

readBinaryFile()

Reads the contents of a file as a raw Uint8Array.

Android	iOS	Web	Desktop
Yes	Yes	No	No

Parameters

Name	Type	Required	Description
path	string	Yes	The absolute path to the file.

Returns

Promise<{ success: boolean; data: Uint8Array }>

`writeTextFile(path, contents)`

Writes a UTF-8 string to the specified absolute file path. Creates directories if necessary.

Parameters:

path (string): The absolute file path.
contents (string): The text contents to write.

Returns: Promise<void>

`readBinaryFile(path)`

Reads raw binary data, returning a zero-copy ArrayBuffer without JSON serialization overhead.

Parameters:

path (string): The absolute file path.

Returns: Promise<{bytes: ArrayBuffer}>

File System

On this page