@playstack/local-first

Runtime-neutral atomic local mutations, durable outbox state, cursor pulls, conflicts, retries, and synchronization leases.

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@playstack/local-first supplies one synchronization engine for web, mobile, and desktop clients while leaving product entities and platform storage explicit.

const client = createLocalFirstClient({
  definition,
  storage,
  transport,
  runtime,
  scope: () => ({ type: 'account', id: currentAccountId }),
  clock,
  ids,
})

await client.mutate('draft.save', draft)
await client.sync()

An optimistic projection and its outbound mutation commit in one local transaction. Sync then acquires a scoped lease, pushes bounded batches, records retry, conflict, or dead-letter outcomes, and applies pulled changes with their cursor atomically.

Authentication, authorization, conflict policy, product schemas, retention, attachments, and the server change source remain application-owned. The package does not make payments, inventory, or other invariant-heavy writes automatically safe offline.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/local-first@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Shipped adapters and non-goals

IndexedDB and Expo SQLite adapters are published. React local-first bindings, a Tauri transaction bridge and Nest sync protocol bindings remain planned. Platform storage and process-local leases do not establish a native filesystem transaction or replace product revision/tombstone protocols.

Keep canonical files, unsaved buffers, conflict recovery, retention and atomic grouped changes under product policy. A generic outbox cannot qualify a native sync replacement without crash/restart and real-client conformance tests.

API entry points and requirements

Reference snapshot: @playstack/local-first@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Public entry point	Declaration file
`@playstack/local-first`	`./dist/index.d.ts`
`@playstack/local-first/testing`	`./dist/testing.d.ts`
`@playstack/local-first/playstack.integration.json`	No TypeScript declaration (asset or metadata export).
`@playstack/local-first/package.json`	No TypeScript declaration (asset or metadata export).

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.