writeFile

Category: Storage

Namespace: web.storage.writeFile

Description

Write a text file into the app's dedicated storage folder. If the file already exists it is overwritten. The folder is created automatically at startup — no setup needed.

Syntax

await web.storage.writeFile({ name: 'filename.ext', content: 'file content' });

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	File name only (e.g. `save1.json`). Path separators and `..` are stripped automatically
`content`	string	Yes	The text content to write. UTF-8 encoded

Returns

Promise<boolean> - Resolves true on success, rejects with an error on failure

Example

Simple example

await web.storage.writeFile({ name: 'notes.txt', content: 'Hello world' });

Practical example — save a game state

async function saveGame(slot) {
    const saveData = {
        level: currentLevel,
        health: player.health,
        position: player.position,
        inventory: player.inventory,
        savedAt: new Date().toISOString()
    };
    await web.storage.writeFile({
        name: `save${slot}.json`,
        content: JSON.stringify(saveData, null, 2)
    });
    showMessage(`Game saved to slot ${slot}`);
}

Advanced example — write a CSV export

async function exportScores(scores) {
    const csv = ['Name,Score,Date'];
    for (const entry of scores) {
        csv.push(`${entry.name},${entry.score},${entry.date}`);
    }
    await web.storage.writeFile({
        name: 'scores.csv',
        content: csv.join('\n')
    });
    const dir = await web.storage.getDir();
    await web.shell.showInExplorer({ path: dir });
}

Error Handling

try {
    await web.storage.writeFile({ name: 'data.json', content: jsonStr });
} catch (e) {
    alert('Could not save file: ' + e.message);
}

web.storage.readFile() - Read a file from the storage folder
web.storage.deleteFile() - Delete a file from the storage folder
web.storage.listFiles() - List all files in the storage folder
web.storage.getDir() - Get the full path to the storage folder

Notes

Files are written as UTF-8 text — suitable for JSON, CSV, plain text, HTML, etc.
For binary files use web.files.writeFileAsBase64() with the path from getDir()
File names are sanitized: /, \, and .. are removed to prevent writing outside the storage folder
storage.json is reserved for the key-value store — avoid using it as a file name