Data Storage
Where scripts keep data and how long it is retained.
Each project has three directories that scripts read and write with fs and node:sqlite. They differ in how long the data is kept:
| Directory | Path | Retention | Sync |
|---|---|---|---|
| Persistent data | os.homedir() (process.env.HOME) | Kept until the project is deleted | Follows the project: iCloud Drive when iCloud sync is on |
| Temporary | os.tmpdir() (process.env.TMPDIR) | Kept across runs; the system may clear it when storage is low; deleted with the project | This device only |
| Build output | process.cwd() | Cleared before every run | โ |
Relative paths resolve against process.cwd(), so files written with a relative path are lost on the next run.
Persistent data
Files written under os.homedir() with fs, and SQLite databases created there with node:sqlite, are kept across runs. The app, widgets, and actions all see the same data.
import { DatabaseSync } from 'node:sqlite';
import os from 'node:os';
import { join } from 'node:path';
const db = new DatabaseSync(join(os.homedir(), 'app.db'));- Each project has its own data directory so scripts do not overwrite each other's files. This is a default location, not a security boundary: scripts are trusted code and can access any path the app can.
- The data is stored with your projects: when iCloud sync is on it is kept in iCloud Drive, and when you change the sync setting it moves along with the projects. It is deleted together with the project.
- iCloud syncs whole files, not database transactions. Avoid writing the same SQLite database from several devices at the same time, or the changes may conflict.
Temporary data
os.tmpdir() suits caches that can be rebuilt, such as downloaded images. It stays on this device and is not synced to iCloud.
How is this guide?
Last updated on