Configuration Reference

Complete persist.config.ts format with all options for stores, adapters, sync, encryption, and retention.

Config file

Persist reads configuration from persist.config.ts in the project root. The file exports a default object conforming to the PersistConfig type.

import type { PersistConfig } from "@cuitty/persist";

export default {
  stores: { /* ... */ },
  sync: { /* ... */ },
  logging: { /* ... */ },
} satisfies PersistConfig;

Store configuration

Each key in stores defines a named store with its adapter and options.

export default {
  stores: {
    "my-app": {
      adapter: "sqlite",
      path: "./data/my-app.db",
      sqlite: {
        walMode: true,
        busyTimeout: 5000,
      },
    },
    analytics: {
      adapter: "postgres",
      connectionString: "postgresql://user:pass@host:5432/persist",
      postgres: {
        schema: "analytics",
        poolSize: 10,
      },
    },
    assets: {
      adapter: "s3",
      s3: {
        bucket: "my-assets",
        region: "us-east-1",
      },
    },
  },
};

Sync configuration

Global sync settings apply to all stores unless overridden at the store level.

export default {
  sync: {
    enabled: true,
    remote: "https://sync.persist.one",
    interval: 10_000,
    strategy: "last-write-wins",
    batchSize: 200,
    retryBackoff: {
      initial: 1000,
      max: 60_000,
      multiplier: 2,
    },
  },
};

Per-store overrides:

export default {
  stores: {
    tasks: {
      adapter: "sqlite",
      path: "./tasks.db",
      sync: {
        interval: 2000,     // override global interval
        strategy: "merge",
        merge: (local, remote) => ({ ...local.value, ...remote.value }),
      },
    },
  },
};

Encryption configuration

export default {
  stores: {
    secrets: {
      adapter: "sqlite",
      path: "./secrets.db",
      encryption: {
        enabled: true,
        algorithm: "aes-256-gcm",  // only supported algorithm
        masterKey: "${PERSIST_MASTER_KEY}",  // env var interpolation
        keyRotationDays: 90,
      },
    },
  },
};

Environment variable interpolation is supported in string values using ${VAR_NAME} syntax.

Retention configuration

export default {
  stores: {
    events: {
      adapter: "sqlite",
      path: "./events.db",
      retention: {
        maxAge: "90d",        // duration string: 30d, 12h, 60m
        maxCount: 50_000,
        pruneInterval: "1h",
      },
    },
  },
};

Logging

export default {
  logging: {
    level: "info",      // "debug" | "info" | "warn" | "error"
    format: "json",     // "json" | "text"
    destination: "stderr", // "stderr" | "stdout" | file path
  },
};

Environment variables