XDG-compliant app config and data storage for TypeScript. Type-safe, atomic writes, auto-migrations. Zero deps.
bun add @corvid-agent/dotfile
# or
npm install @corvid-agent/dotfileimport { dotfile } from "@corvid-agent/dotfile"; const config = dotfile({ name: "my-app", defaults: { theme: "dark", fontSize: 14, notifications: true, }, }); // Read (returns defaults if no file exists) const settings = config.read(); // Write (atomic — won't corrupt on crash) config.write({ theme: "light", fontSize: 16, notifications: false }); // Update (shallow merge) config.update({ fontSize: 18 }); // Check / delete config.exists(); // true config.path(); // ~/.config/my-app/config.json config.delete();
- XDG-compliant — respects
XDG_CONFIG_HOME/XDG_DATA_HOMEon Linux,~/Library/Application Supporton macOS,%APPDATA%on Windows - Type-safe — full TypeScript generics, your config type flows through read/write/update
- Atomic writes — uses write-to-temp + rename to prevent corruption
- Auto-migrations — optional
migrate()function for schema evolution - Zero deps — only uses Node.js built-ins
| Platform | Config dir | Data dir |
|---|---|---|
| Linux | ~/.config/<name>/ |
~/.local/share/<name>/ |
| macOS | ~/Library/Application Support/<name>/ |
~/Library/Application Support/<name>/ |
| Windows | %APPDATA%/<name>/ |
%LOCALAPPDATA%/<name>/ |
const config = dotfile({ name: "my-app", defaults: { theme: "dark", fontSize: 14 }, migrate: (data, version) => { if (!version || version < 2) { // v1 → v2: rename "color" to "theme" const d = data as any; return { data: { theme: d.color || d.theme || "dark", fontSize: d.fontSize || 14 }, version: 2, }; } return { data: data as any, version }; }, });
MIT