Quickstart

Install Persist and create your first local-first store in under five minutes.

Install the SDK

Add @cuitty/persist to your project using your preferred package manager:

npm install @cuitty/persist
# or
bun add @cuitty/persist

Create a store

A store is the primary unit of storage in Persist. The createStore function accepts a name and an adapter configuration. By default, Persist uses SQLite so your data lives on disk immediately with no server required.

import { createStore } from "@cuitty/persist";

const store = await createStore("my-app", {
  adapter: "sqlite",
  path: "./data/my-app.db",
});

Write and read a record

Records are key-value documents. Each record has a string key and a JSON-serializable value. Persist tracks metadata (timestamps, version vectors) automatically.

// Put a record
await store.records.put("user:1", {
  name: "Alice",
  email: "alice@example.com",
  plan: "pro",
});

// Get it back
const user = await store.records.get("user:1");
console.log(user.value.name); // "Alice"

Enable sync

To replicate data across devices, add a sync target. Persist queues writes locally and pushes them when a connection is available. Conflict resolution defaults to last-write-wins but can be customized per store.

import { createStore, enableSync } from "@cuitty/persist";

const store = await createStore("my-app", {
  adapter: "sqlite",
  path: "./data/my-app.db",
});

await enableSync(store, {
  remote: "https://sync.persist.one",
  strategy: "last-write-wins",
});

Once sync is enabled, every put, append, or delete is queued and pushed in the background. If the device is offline, operations accumulate locally and flush when connectivity returns.

Next steps

• Learn about the four store classes (records, events, blobs, kv)
• Explore available adapters for different backends
• Set up P2P sync for direct device-to-device replication