FileSystem

import fs from "@native/fs";  // requires "filesystem" permission

The fs module gives each script a sandboxed file system rooted at its own data/ folder - <your script>/data. Scripts cannot see each other’s files.

All paths are relative to your script’s data/ folder. Absolute paths or anything that escapes the sandbox (e.g. ../../secret) will throw "path escapes sandbox". The folder is excluded from the file watcher, so writing to it does not trigger a reload.

Overview

Reading & writing

Read, write, and append file contents - binary by default, UTF-8 with an encoding option.

Directories

Create, remove, and list directory entries.

Metadata & checks

Check existence, read file size, and inspect types.

Move, copy & watch

Rename, copy, truncate, and watch paths for changes.

Reading & writing

fs.readFile

fs.readFile(path: string): Promise<Uint8Array>
fs.readFile(path: string, encoding: "utf8"): Promise<string>

fs.readFileSync(path: string): Uint8Array
fs.readFileSync(path: string, encoding: "utf8"): string

Reads the full contents of a file. By default returns raw bytes as a Uint8Array. Pass "utf8" as the second argument to decode the file and get a string instead.

// Binary (default) - returns Uint8Array
const raw = await fs.readFile("assets/icon.png");
console.log(`${raw.byteLength} bytes`);

// UTF-8 - returns string
const json = await fs.readFile("profiles/player1.json", "utf8");
const profile = JSON.parse(json);
console.log(`Welcome back, ${profile.name}!`);

// Sync variants work the same way
const data = fs.readFileSync("data.bin");           // Uint8Array
const text = fs.readFileSync("config.json", "utf8"); // string

fs.writeFile

fs.writeFile(path: string, data: string | Uint8Array | ArrayBuffer): Promise<true>
fs.writeFileSync(path: string, data: string | Uint8Array | ArrayBuffer): true

Writes data to a file, replacing it if it already exists. Accepts a UTF-8 string, a Uint8Array, or an ArrayBuffer.

// String
const save = { level: 12, hp: 85, inventory: ["sword", "shield", "potion"] };
await fs.writeFile("saves/slot1.json", JSON.stringify(save, null, 2));

// Binary
const bytes = new Uint8Array([0x89, 0x50, 0x4E, 0x47]);
await fs.writeFile("output.bin", bytes);

fs.appendFile

fs.appendFile(path: string, data: string | Uint8Array | ArrayBuffer): Promise<true>
fs.appendFileSync(path: string, data: string | Uint8Array | ArrayBuffer): true

Appends data to the end of a file. Creates the file if it doesn’t exist. Accepts a UTF-8 string, a Uint8Array, or an ArrayBuffer.

async function log(message: string) {
    const line = `[${new Date().toISOString()}] ${message}\n`;
    await fs.appendFile("debug.log", line);
}

await log("Script started");
await log("Player spawned at (100, 200)");

Prefer the async variants (readFile, writeFile, appendFile) in event handlers and loops. Use the *Sync variants only during initialization where blocking I/O is acceptable.

Directories

fs.mkdir

fs.mkdir(path: string, recursive?: boolean): Promise<void>
fs.mkdirSync(path: string, recursive?: boolean): void

Creates a directory. Pass true as the second argument to create the full path at once (like mkdir -p).

await fs.mkdir("saves/player_42/backups", true);

fs.rmdir

fs.rmdir(path: string, recursive?: boolean): Promise<void>

Removes a directory. Pass true to delete it recursively.

await fs.rmdir("saves/old_profile", true);

fs.readdir

fs.readdir(path: string): Promise<string[]>
fs.readdirSync(path: string): string[]

Returns an array of entry names (files and subdirectories) inside path.

const entries = await fs.readdir("saves");
// ["slot1.json", "slot2.json", "autosave.json", "backups"]

// Sync - build a script picker
const files = fs.readdirSync("scripts");
const jsFiles = files.filter(f => fs.path.extname(f) === ".js");

Metadata & checks

fs.exists

fs.exists(path: string): Promise<boolean>
fs.existsSync(path: string): boolean

Returns true if the path exists (file or directory), false otherwise.

if (await fs.exists("saves/autosave.json")) {
    console.log("Autosave found, loading...");
} else {
    console.log("No autosave, starting fresh.");
}

fs.stat

fs.stat(path: string): Promise<StatResult>
fs.statSync(path: string): StatResult

Returns a StatResult object describing the path.

Field	Type	Description
`size`	`number`	File size in bytes (`0` for directories)
`isFile`	`boolean`	`true` if a regular file
`isDirectory`	`boolean`	`true` if a directory

const info = await fs.stat("saves/slot1.json");

if (info.isFile) {
    console.log(`Save file size: ${(info.size / 1024).toFixed(1)} KB`);
}

Move, copy & watch

fs.unlink

fs.unlink(path: string): Promise<void>
fs.unlinkSync(path: string): boolean

Deletes a single file. The async variant rejects if the file doesn’t exist; the sync variant returns false instead of throwing.

await fs.writeFile("temp_export.txt", buildExportData());
await uploadToServer("temp_export.txt");
await fs.unlink("temp_export.txt");

fs.rename

fs.rename(oldPath: string, newPath: string): Promise<void>

Moves or renames a file/directory within the sandbox.

if (await fs.exists("debug.log")) {
    await fs.rename("debug.log", "debug_prev.log");
}
await fs.writeFile("debug.log", "");

fs.copyFile

fs.copyFile(src: string, dst: string): Promise<void>

Copies a file. Overwrites dst if it already exists.

// Backup before modifying
await fs.copyFile("config.json", "config.backup.json");

const config = JSON.parse(await fs.readFile("config.json"));
config.debug = true;
await fs.writeFile("config.json", JSON.stringify(config, null, 2));

fs.truncate

fs.truncate(path: string, length?: number): Promise<void>

Resizes a file to length bytes. Defaults to 0 (clears the file). If the file is shorter than length, it is padded with null bytes.

// Clear a log without deleting it
await fs.truncate("debug.log");

// Keep only the first 1 KB
await fs.truncate("large_output.txt", 1024);

fs.watch

fs.watch(
    path: string,
    callback: (event: "change" | "rename" | "error", filename: string) => void,
    options?: { recursive?: boolean }
): FSWatcher

Watches a file or directory for changes. Returns an FSWatcher - call .close() to stop.

Event	Trigger
`"change"`	File content was modified
`"rename"`	File was created, deleted, or renamed
`"error"`	A watcher error occurred

const watcher = fs.watch("saves", (event, filename) => {
    if (event === "error") { console.error("Watch error:", filename); return; }
    console.log(`[${event}] ${filename}`);
}, { recursive: true });

setTimeout(() => watcher.close(), 60_000);

const configWatcher = fs.watch("config.json", (event) => {
    if (event === "change") {
        try {
            applyConfig(JSON.parse(fs.readFileSync("config.json")));
            console.log("Config hot-reloaded!");
        } catch (e) {
            console.error("Reload failed:", e);
        }
    }
});

Path utilities - `fs.path`

Pure string helpers - they do not touch the file system.

Function	Returns	Example
`fs.path.join(...segments)`	`string`	`join("saves","p1","data.json")` → `"saves/p1/data.json"`
`fs.path.basename(path)`	`string`	`basename("saves/p1/data.json")` → `"data.json"`
`fs.path.dirname(path)`	`string`	`dirname("saves/p1/data.json")` → `"saves/p1"`
`fs.path.extname(path)`	`string`	`extname("archive.tar.gz")` → `".gz"`
`fs.path.resolve(...segments)`	`string`	Resolves to absolute path from cwd
`fs.path.isAbsolute(path)`	`boolean`	`isAbsolute("/data/f.txt")` → `true`

Recipes

JSON key-value store

class JsonStore {
    constructor(private file: string) {}

    async load(fallback = {}) {
        return (await fs.exists(this.file))
            ? JSON.parse(await fs.readFile(this.file))
            : fallback;
    }

    async save(data: object) {
        await fs.writeFile(this.file, JSON.stringify(data, null, 2));
    }

    async update(fn: (d: any) => any) {
        const result = fn(await this.load());
        await this.save(result);
        return result;
    }
}

const db = new JsonStore("playerdata.json");
await db.save({ kills: 0, deaths: 0 });
await db.update(d => ({ ...d, kills: d.kills + 1 }));

Save slot manager

const SAVE_DIR = "saves";

async function saveGame(slot: number, data: object) {
    await fs.mkdir(SAVE_DIR, true);
    const file = fs.path.join(SAVE_DIR, `slot${slot}.json`);
    if (await fs.exists(file)) await fs.copyFile(file, `${file}.bak`);
    await fs.writeFile(file, JSON.stringify({ ...data, savedAt: new Date().toISOString() }, null, 2));
}

async function loadGame(slot: number) {
    const file = fs.path.join(SAVE_DIR, `slot${slot}.json`);
    return (await fs.exists(file)) ? JSON.parse(await fs.readFile(file)) : null;
}

Log rotation

const LOG_FILE = "app.log";
const MAX_SIZE = 50 * 1024; // 50 KB

async function writeLog(level: string, message: string) {
    if (await fs.exists(LOG_FILE)) {
        const { size } = await fs.stat(LOG_FILE);
        if (size >= MAX_SIZE) {
            if (await fs.exists("app_prev.log")) await fs.unlink("app_prev.log");
            await fs.rename(LOG_FILE, "app_prev.log");
        }
    }
    await fs.appendFile(LOG_FILE, `[${new Date().toISOString()}] [${level}] ${message}\n`);
}

Error handling

All async functions return Promises that reject on failure. Sync functions throw directly.

// Async
try {
    const data = await fs.readFile("might_not_exist.json");
} catch (err) {
    console.error("Read failed:", err);
}

// Sync
try {
    fs.writeFileSync("output.txt", "Hello");
} catch (err) {
    console.error("Write failed:", err);
}

// Guard pattern - cleanest when the file is optional
if (await fs.exists("optional.json")) {
    const content = await fs.readFile("optional.json");
}

Security

All paths resolve relative to scripts/data. Any path that escapes the sandbox throws "path escapes sandbox".

The following will always throw - absolute paths and directory traversal are blocked at the sandbox boundary:

await fs.readFile("/etc/passwd");          // absolute path
await fs.readFile("../../secrets.txt");    // traversal
await fs.writeFile("../outside.txt", ""); // traversal

Overview

Modules

Types

Overview

Reading & writing

Directories

Metadata & checks

Move, copy & watch

Reading & writing

fs.readFile

fs.writeFile

fs.appendFile

Directories

fs.mkdir

fs.rmdir

fs.readdir

Metadata & checks

fs.exists

fs.stat

Move, copy & watch

fs.unlink

fs.rename

fs.copyFile

fs.truncate

fs.watch

Path utilities - `fs.path`

Recipes

JSON key-value store

Save slot manager

Log rotation

Error handling

Security

​Overview

Reading & writing

Directories

Metadata & checks

Move, copy & watch

​Reading & writing

​fs.readFile

​fs.writeFile

​fs.appendFile

​Directories

​fs.mkdir

​fs.rmdir

​fs.readdir

​Metadata & checks

​fs.exists

​fs.stat

​Move, copy & watch

​fs.unlink

​fs.rename

​fs.copyFile

​fs.truncate

​fs.watch

​Path utilities - fs.path

​Recipes

​JSON key-value store

​Save slot manager

​Log rotation

​Error handling

​Security

Overview

Reading & writing

fs.readFile

fs.writeFile

fs.appendFile

Directories

fs.mkdir

fs.rmdir

fs.readdir

Metadata & checks

fs.exists

fs.stat

Move, copy & watch

fs.unlink

fs.rename

fs.copyFile

fs.truncate

fs.watch

Path utilities - `fs.path`

Recipes

JSON key-value store

Save slot manager

Log rotation

Error handling

Security