@livestore/livestore 0.4.0-dev.21 → 0.4.0-dev.23

package/docs/platform-adapters/expo-adapter/index.md

@@ -1,245 +0,0 @@
-# Expo Adapter
-
-The Expo adapter enables LiveStore in React Native applications built with [Expo](https://expo.dev). It uses native SQLite via `expo-sqlite` for high-performance local persistence on iOS and Android devices.
-
-## Key Features
-
-- **Signals-based reactivity** — High-performance state management with fine-grained updates
-- **iOS and Android support** — Works seamlessly on both platforms with native performance
-- **Native SQLite storage** — Uses `expo-sqlite` for fast, reliable persistence directly on the device
-- **Offline-first** — Full functionality without network connectivity; syncs when connected
-- **Real-time sync** — Optional sync backend integration for multi-device data synchronization
-- **Integrated devtools** — Debug and inspect your store via the [LiveStore Devtools](/building-with-livestore/devtools)
-
-## Requirements
-
-- [Expo New Architecture](https://docs.expo.dev/guides/new-architecture/) (Fabric) must be enabled
-- `expo-sqlite` ^16.0.0
-- `expo-application` ^7.0.0
-
-:::note
-Expo Web is not currently supported. See [#130](https://github.com/livestorejs/livestore/issues/130) for progress.
-:::
-
-## Installation
-
-```bash
-npm install @livestore/adapter-expo @livestore/livestore @livestore/react expo-sqlite expo-application
-```
-
-For a complete setup including sync and devtools, see the [Expo getting started guide](/getting-started/expo).
-
-## Basic Usage
-
-Create an adapter and wrap your app with the `LiveStoreProvider`:
-
-## `reference/platform-adapters/expo-adapter/usage.tsx`
-
-```tsx filename="reference/platform-adapters/expo-adapter/usage.tsx"
-
-const adapter = makePersistedAdapter()
-
-export const App = () => (
-  <SafeAreaView style={{ flex: 1 }}>
-    <LiveStoreProvider
-      schema={schema}
-      adapter={adapter}
-      storeId="my-app"
-      batchUpdates={batchUpdates}
-      renderLoading={(status) => <Text>Loading ({status.stage})...</Text>}
-      renderError={(error) => <Text>Error: {String(error)}</Text>}
-    >
-      {/* Your app content */}
-    </LiveStoreProvider>
-  </SafeAreaView>
-)
-```
-
-### `reference/platform-adapters/expo-adapter/schema.ts`
-
-```ts filename="reference/platform-adapters/expo-adapter/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} as const
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-The adapter requires minimal configuration. For more details on the provider props, see the [React integration guide](/framework-integrations/react-integration).
-
-## Configuration Options
-
-## `reference/platform-adapters/expo-adapter/adapter.ts`
-
-```ts filename="reference/platform-adapters/expo-adapter/adapter.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const adapter = makePersistedAdapter({
-  storage: { subDirectory: 'my-app' },
-})
-```
-
-### Available Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `storage.subDirectory` | `string` | Subdirectory within the default SQLite location for organizing databases |
-| `sync` | `SyncOptions` | Sync backend configuration (see [Syncing](/building-with-livestore/syncing)) |
-| `clientId` | `string` | Custom client identifier (defaults to device ID) |
-| `sessionId` | `string` | Session identifier (defaults to `'static'`) |
-| `resetPersistence` | `boolean` | Clear local databases on startup (development only) |
-
-## Adding a Sync Backend
-
-Connect to a sync backend for multi-device synchronization:
-
-## `reference/platform-adapters/expo-adapter/sync-backend.ts`
-
-```ts filename="reference/platform-adapters/expo-adapter/sync-backend.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const adapter = makePersistedAdapter({
-  sync: { backend: makeWsSync({ url: 'wss://your-sync-backend.com' }) },
-})
-```
-
-See the [Syncing documentation](/building-with-livestore/syncing) for available sync providers and configuration options.
-
-## Platform Notes
-
-### Android
-
-Android requires HTTPS for network connections by default. During development with a local sync backend using `http://` or `ws://`, add `expo-build-properties` to allow cleartext traffic:
-
-```bash
-npx expo install expo-build-properties
-```
-
-Then configure `app.json`:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "expo-build-properties",
-        {
-          "android": {
-            "usesCleartextTraffic": true
-          }
-        }
-      ]
-    ]
-  }
-}
-```
-
-See [Expo build properties documentation](https://docs.expo.dev/versions/latest/sdk/build-properties/#pluginconfigtypeandroid) for more details.
-
-### iOS
-
-No special configuration required. The adapter automatically retrieves the iOS vendor ID for client identification.
-
-## Devtools
-
-LiveStore provides integrated devtools for debugging your store. In development, press `shift + m` in the Expo CLI terminal, then select "LiveStore Devtools" to open the browser-based inspector.
-
-See the [Devtools reference](/building-with-livestore/devtools) for full documentation.
-
-## Storage & Persistence
-
-### Database Location
-
-Databases are stored in the device's SQLite directory. The exact path depends on your setup:
-
-**Expo Go:**
-```bash
-open $(find $(xcrun simctl get_app_container booted host.exp.Exponent data) -path "*/Documents/ExponentExperienceData/*livestore*" -print -quit)/SQLite
-```
-
-**Development builds:**
-```bash
-open $(xcrun simctl get_app_container booted [APP_BUNDLE_ID] data)/Documents/SQLite
-```
-
-Replace `[APP_BUNDLE_ID]` with your app's bundle identifier (e.g., `dev.livestore.myapp`).
-
-### Resetting Local Persistence
-
-During development, you can clear local databases on startup:
-
-## `reference/platform-adapters/expo-adapter/reset-persistence.ts`
-
-```ts filename="reference/platform-adapters/expo-adapter/reset-persistence.ts"
-
-const resetPersistence = process.env.EXPO_PUBLIC_LIVESTORE_RESET === 'true'
-
-const _adapter = makePersistedAdapter({
-  storage: { subDirectory: 'dev' },
-  resetPersistence,
-})
-```
-
-:::caution
-This deletes all local LiveStore data for the configured store. It only clears on-device data and does not affect any connected sync backend. Ensure this flag is disabled in production builds.
-:::
-
-## Architecture
-
-The Expo adapter runs LiveStore directly in the main JavaScript thread, using native SQLite bindings provided by `expo-sqlite`. This differs from the [web adapter](/platform-adapters/web-adapter), which uses web workers and WASM-based SQLite.
-
-```
-┌─────────────────────────────────────────┐
-│           React Native App              │
-│  ┌───────────────────────────────────┐  │
-│  │         LiveStore Client          │  │
-│  │  ┌─────────────┐ ┌─────────────┐  │  │
-│  │  │ State DB    │ │ Eventlog DB │  │  │
-│  │  │(expo-sqlite)│ │(expo-sqlite)│  │  │
-│  │  └─────────────┘ └─────────────┘  │  │
-│  └───────────────────────────────────┘  │
-└─────────────────────────────────────────┘
-                     │
-                     ▼ WebSocket
-            ┌───────────────┐
-            │ Sync Backend  │
-            │  (optional)   │
-            └───────────────┘
-```
-
-## Future Improvements
-
-We're exploring moving database operations to a background thread to further improve UI responsiveness during intensive writes. Follow [livestore/livestore](https://github.com/livestorejs/livestore) for updates.
-
-## See Also
-
-- [Expo Getting Started Guide](/getting-started/expo) — Complete setup tutorial
-- [Expo Adapter Examples](/examples/expo-adapter) — Example applications
-- [React Integration](/framework-integrations/react-integration) — Provider and hooks documentation
-- [Syncing](/building-with-livestore/syncing) — Multi-device synchronization
-- [Devtools](/building-with-livestore/devtools) — Debugging and inspection tools

package/docs/platform-adapters/node-adapter/index.md

@@ -1,160 +0,0 @@
-# Node adapter
-
-Works with Node.js, Bun and Deno.
-
-## Example
-
-## `reference/platform-adapters/node-adapter/adapter.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/adapter.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const adapter = makeAdapter({
-  storage: { type: 'fs' },
-  // or in-memory:
-  // storage: { type: 'in-memory' },
-  sync: { backend: makeWsSync({ url: 'ws://localhost:8787' }) },
-  // To enable devtools:
-  // devtools: { schemaPath: new URL('./schema.ts', import.meta.url) },
-})
-```
-
-## Resetting local persistence
-
-During development you can instruct the adapter to wipe the locally persisted state and eventlog databases on startup:
-
-## `reference/platform-adapters/node-adapter/reset-persistence.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/reset-persistence.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const resetPersistence = process.env.NODE_ENV !== 'production' && Boolean(process.env.RESET_LIVESTORE)
-
-const adapter = makeAdapter({
-  storage: { type: 'fs' },
-  resetPersistence,
-})
-```
-
-:::caution
-This will delete all local data for the given `storeId` and `clientId`. It only clears local persistence and does not reset any connected sync backend. Only enable it for debugging scenarios.
-:::
-
-### Worker adapter
-
-The worker adapter can be used for more advanced scenarios where it's preferable to reduce the load of the main thread and run persistence/syncing in a worker thread.
-
-## `reference/platform-adapters/node-adapter/worker-main.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/worker-main.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: snippet keeps adapter inline for docs */
-// ---cut---
-
-const adapter = makeWorkerAdapter({
-  storage: { type: 'fs' },
-  workerUrl: new URL('./livestore.worker.js', import.meta.url),
-})
-```
-
-## `reference/platform-adapters/node-adapter/worker-worker.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/worker-worker.ts"
-
-makeWorker({
-  schema,
-  sync: { backend: makeWsSync({ url: 'ws://localhost:8787' }) },
-})
-```
-
-### `reference/platform-adapters/node-adapter/schema.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} as const
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-#### Logging
-
-You can control what the Node worker logs and how it's formatted.
-Pass two optional options to `makeWorker`:
-
-- `logger` — where/format of logs (e.g. pretty console output)
-- `logLevel` — how verbose logs are (`LogLevel.None` silences logs)
-
-## `reference/platform-adapters/node-adapter/worker-logging.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/worker-logging.ts"
-
-makeWorker({
-  schema,
-  // readable console output by thread name
-  logger: Logger.prettyWithThread('livestore-node-leader-thread'),
-  // choose verbosity: None | Error | Warning | Info | Debug
-  logLevel: LogLevel.Info,
-})
-```
-
-### `reference/platform-adapters/node-adapter/schema.ts`
-
-```ts filename="reference/platform-adapters/node-adapter/schema.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} as const
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-Tips:
-- Use `LogLevel.None` to keep test output quiet.
-- Keep the default (Debug) when diagnosing issues.

package/docs/platform-adapters/tauri-adapter/index.md

@@ -1,15 +0,0 @@
-# Tauri adapter
-
-## Native Tauri adapter
-
-While LiveStore doesn't yet support a native Tauri adapter (see [this issue](https://github.com/livestorejs/livestore/issues/125) for more details), you can already use the [web adapter](./web-adapter.md) with Tauri.
-
-The goal of the native Tauri adapter is for LiveStore to leverage native platform APIs and capabilities including:
-
-- Native file system access (instead of going through the browser abstraction layer)
-- Background sync capabilities
-- ...
-
-## Example using the web adapter
-
-See this example of a Tauri app using the web adapter: [tauri-todomvc-sync-cf](https://github.com/bohdanbirdie/tauri-todomvc-sync-cf)

package/docs/platform-adapters/web-adapter/index.md

@@ -1,218 +0,0 @@
-# Web adapter
-
-## Installation
-
-```bash
-npm install @livestore/adapter-web @livestore/wa-sqlite
-```
-
-## Example
-
-## `reference/platform-adapters/web-adapter/main.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/main.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const adapter = makePersistedAdapter({
-  storage: { type: 'opfs' },
-  worker: LiveStoreWorker,
-  sharedWorker: LiveStoreSharedWorker,
-})
-```
-
-## `reference/platform-adapters/web-adapter/livestore.worker.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/livestore.worker.ts"
-
-makeWorker({ schema })
-```
-
-### `reference/platform-adapters/web-adapter/schema/index.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/schema/index.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} as const
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-## Adding a sync backend
-
-## `reference/platform-adapters/web-adapter/sync-backend.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/sync-backend.ts"
-
-makeWorker({ schema, sync: { backend: makeWsSync({ url: 'ws://localhost:8787' }) } })
-```
-
-### `reference/platform-adapters/web-adapter/schema/index.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/schema/index.ts"
-
-const tables = {
-  todos: State.SQLite.table({
-    name: 'todos',
-    columns: {
-      id: State.SQLite.text({ primaryKey: true }),
-      text: State.SQLite.text(),
-      completed: State.SQLite.boolean({ default: false }),
-    },
-  }),
-} as const
-
-const events = {
-  todoCreated: Events.synced({
-    name: 'v1.TodoCreated',
-    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
-  }),
-} as const
-
-const materializers = State.SQLite.materializers(events, {
-  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
-    tables.todos.insert({ id, text, completed: false }),
-  ),
-})
-
-const state = State.SQLite.makeState({ tables, materializers })
-
-export const schema = makeSchema({ events, state })
-```
-
-## In-memory adapter
-
-You can also use the in-memory adapter which can be useful in certain scenarios (e.g. testing).
-
-## `reference/platform-adapters/web-adapter/in-memory.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/in-memory.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const adapter = makeInMemoryAdapter()
-```
-
-## Web worker
-
-- Make sure your schema doesn't depend on any code which needs to run in the main thread (e.g. avoid importing from files using React)
-  - Unfortunately this constraints you from co-locating your table definitions in component files.
-  - You might be able to still work around this by using the following import in your worker:
-    ```ts
-
-    ```
-
-### Why is there a dedicated web worker and a shared worker?
-
-- Shared worker:
-  - Needed to allow tabs to communicate with each other using a binary message channel.
-  - The shared worker mostly acts as a proxy to the dedicated web worker.
-- Dedicated web worker (also called "leader worker" via leader election mechanism using web locks):
-  - Acts as the leader/single writer for the storage.
-  - Also handles connection to sync backend.
-  - Currently needed for synchronous OPFS API which isn't supported in a shared worker. (Hopefully won't be needed in the future anymore.)
-
-### Why not use a service worker?
-
-- While service workers seem similar to shared workers (i.e. only a single instance across all tabs), they serve different purposes and have different trade-offs.
-- Service workers are meant to be used to intercept network requests and tend to "shut down" when there are no requests for some period of time making them unsuitable for our use case.
-- Also note that service workers don't support some needed APIs such as OPFS.
-
-## Storage
-
-LiveStore currently only support OPFS to locally persist its data. In the future we might add support for other storage types (e.g. IndexedDB).
-
-During development (`NODE_ENV !== 'production'`), LiveStore automatically copies older state database files into `archive/` inside the OPFS directory for the store (e.g. `livestore-<storeId>@<version>/archive/`). The three most recent copies are retained so you can inspect pre-migration data; older archives are pruned. In production, we delete outdated state databases immediately.
-
-LiveStore also uses `window.sessionStorage` to retain the identity of a client session (e.g. tab/window) across reloads.
-
-### Resetting local persistence
-
-Resetting local persistence only clears data stored in the browser and does not affect any connected sync backend.
-
-In case you want to reset the local persistence of a client, you can provide the `resetPersistence` option to the adapter.
-
-## `reference/platform-adapters/web-adapter/reset-persistence.ts`
-
-```ts filename="reference/platform-adapters/web-adapter/reset-persistence.ts"
-/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
-// ---cut---
-
-const resetPersistence = import.meta.env.DEV && new URLSearchParams(window.location.search).get('reset') !== null
-
-if (resetPersistence) {
-  const searchParams = new URLSearchParams(window.location.search)
-  searchParams.delete('reset')
-  window.history.replaceState(null, '', `${window.location.pathname}?${searchParams.toString()}`)
-}
-
-const adapter = makePersistedAdapter({
-  storage: { type: 'opfs' },
-  worker: LiveStoreWorker,
-  sharedWorker: LiveStoreSharedWorker,
-  resetPersistence,
-})
-```
-
-If you want to reset persistence manually, you can:
-
-1. **Clear site data** in Chrome DevTools (Application tab > Storage > Clear site data)
-2. **Use console command** if the above doesn't work due to a Chrome OPFS bug:
-
-```javascript
-const opfsRoot = await navigator.storage.getDirectory();
-await opfsRoot.remove();
-```
-
-Note: Only use this during development while the app is running.
-
-## Architecture diagram
-
-Assuming the web adapter in a multi-client, multi-tab browser application, a diagram looks like this:
-
-![](https://i.imgur.com/NCKbfub.png)
-
-## Other notes
-
-- The web adapter is using some browser APIs that might require a HTTPS connection (e.g. `navigator.locks`). It's recommended to even use HTTPS during local development (e.g. via [Caddy](https://caddyserver.com/docs/automatic-https)).
-
-## Browser support
-
-- Notable required browser APIs: OPFS, SharedWorker, `navigator.locks`, WASM
-- The web adapter of LiveStore currently doesn't work on Android browsers as they don't support the `SharedWorker` API (see [Chromium bug](https://issues.chromium.org/issues/40290702)).
-
-## Best practices
-
-- It's recommended to develop in an incognito window to avoid issues with persistent storage (e.g. OPFS).
-
-## FAQ
-
-### What's the bundle size of the web adapter?
-
-LiveStore with the web adapter adds two parts to your application bundle:
-
-- The LiveStore JavaScript bundle (~180KB gzipped)
-- SQLite WASM (~300KB gzipped)