@corvid-agent/dotfile

XDG-compliant app config and data storage for TypeScript. Type-safe, atomic writes, auto-migrations. Zero deps.

Install

bun add @corvid-agent/dotfile
# or
npm install @corvid-agent/dotfile

Usage

import { 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();

Features

• XDG-compliant — respects XDG_CONFIG_HOME / XDG_DATA_HOME on Linux, ~/Library/Application Support on 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

Config paths

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>/

Migrations

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 };
  },
});

License

MIT