@livestore/livestore 0.4.0-dev.20 → 0.4.0-dev.22

package/docs/patterns/server-side-clients/index.md

@@ -0,0 +1,97 @@
+# Server-side clients
+
+You can also use LiveStore on the server side e.g. via the `@livestore/adapter-node` adapter. This allows you to:
+- have an up-to-date server-side SQLite database (read model)
+- react to events / state changes on the server side (e.g. to send emails/push notifications)
+- commit events on the server side (e.g. for sensitive/trusted operations)
+
+<ServerSideClientDiagram />
+
+Note about the schema: While the `events` schema needs to be shared across all clients, the `state` schema can be different for each client (e.g. to allow for a different SQLite table design on the server side).
+
+## Example
+
+<Tabs>
+  <TabItem label="main.ts">
+
+## `reference/syncing/server-side-clients/main.ts`
+
+```ts filename="reference/syncing/server-side-clients/main.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline setup */
+// ---cut---
+
+const adapter = makeAdapter({
+  storage: { type: 'fs', baseDirectory: 'tmp' },
+  sync: { backend: makeWsSync({ url: 'ws://localhost:8787' }), onSyncError: 'shutdown' },
+})
+
+const store = await createStorePromise({
+  adapter,
+  schema,
+  storeId: 'test',
+  syncPayload: { authToken: 'insecure-token-change-me' },
+})
+
+const todos = store.query(tables.todos.where({ completed: false }))
+```
+
+### `reference/syncing/server-side-clients/schema.ts`
+
+```ts filename="reference/syncing/server-side-clients/schema.ts"
+
+const events = {}
+
+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 }),
+    },
+  }),
+}
+
+const state = State.SQLite.makeState({ tables, materializers: {} })
+
+export const schema = makeSchema({ events, state })
+
+export { tables }
+```
+
+</TabItem>
+  <TabItem label="schema.ts">
+
+## `reference/syncing/server-side-clients/schema.ts`
+
+```ts filename="reference/syncing/server-side-clients/schema.ts"
+
+const events = {}
+
+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 }),
+    },
+  }),
+}
+
+const state = State.SQLite.makeState({ tables, materializers: {} })
+
+export const schema = makeSchema({ events, state })
+
+export { tables }
+```
+
+</TabItem>
+</Tabs>
+
+## Further notes
+
+### Cloudflare Workers
+
+- The `@livestore/adapter-node` adapter doesn't yet work with Cloudflare Workers but you can follow [this issue](https://github.com/livestorejs/livestore/issues/266) for a Cloudflare adapter to enable this use case.
+- Having a `@livestore/adapter-cf-worker` adapter could enable serverless server-side client scenarios.

package/docs/patterns/state-machines/index.md

@@ -1,4 +1,4 @@
-# State Machines
+# State machines
 
 LiveStore can be used to implement state machines or together with existing state machine libraries (e.g. [XState](https://stately.ai/docs/xstate)).
 

package/docs/patterns/storybook/index.md

@@ -1,4 +1,4 @@
-# Storybook Testing (React)
+# Storybook testing (React)
 
 export const CODE = {
   todoInputStories: `import type { Meta, StoryObj } from '@storybook/react'
@@ -20,7 +20,7 @@ export const WithInitialText: Story = {
     ])
   ],
 }`,
-  
+
   storybookPreview: `import React from 'react'
 
 // Default decorator with no seed data
@@ -28,40 +28,57 @@ const LiveStoreDecorator = createLiveStoreDecorator()
 
 export const decorators = [LiveStoreDecorator]`,
 
-  decorator: `import React from 'react'
+  decorator: `import React, { Suspense, useState } from 'react'
+
+const adapter = makeInMemoryAdapter()
 
 // Create LiveStore decorator with optional seeding
 export const createLiveStoreDecorator = (seedEvents = []) => (Story) => {
-  const onBoot = (store) => {
-    // Seed data through events during boot
-    if (seedEvents.length > 0) {
-      store.commit(...seedEvents)
-    }
-  }
+  const [storeRegistry] = useState(() => new StoreRegistry())
 
   return (
-    <LiveStoreProvider
-      schema={schema}
-      adapter={makeInMemoryAdapter()}
-      batchUpdates={batchUpdates}
-      boot={onBoot}
-      renderLoading={(status) => <div>Loading LiveStore ({status.stage})...</div>}
-    >
-      <Story />
-    </LiveStoreProvider>
+    <Suspense fallback={<div>Loading LiveStore...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <StoryWithStore Story={Story} seedEvents={seedEvents} />
+      </StoreRegistryProvider>
+    </Suspense>
   )
+}
+
+const StoryWithStore = ({ Story, seedEvents }) => {
+  const store = useStore({
+    storeId: 'storybook',
+    schema,
+    adapter,
+    batchUpdates,
+    boot: (store) => {
+      if (seedEvents.length > 0) {
+        store.commit(...seedEvents)
+      }
+    },
+  })
+  return <Story />
 }`,
 
-  todoInput: `import React from 'react'
+  todoInput: `import { useStore } from '@livestore/react'
+
+const adapter = makeInMemoryAdapter()
 
 // Define queries (like in TodoMVC)
 const uiState$ = queryDb(tables.uiState.get(), { label: 'uiState' })
 
+const useAppStore = () => useStore({
+  storeId: 'todo-app',
+  schema,
+  adapter,
+  batchUpdates,
+})
+
 export const TodoInput = () => {
-  const { store } = useStore()
+  const store = useAppStore()
   const { newTodoText } = store.useQuery(uiState$)
 
-  const updateNewTodoText = (text: string) => 
+  const updateNewTodoText = (text: string) =>
     store.commit(events.uiStateSet({ newTodoText: text }))
 
   const createTodo = () => {
@@ -110,13 +127,13 @@ export const tables = {
   // Client document for UI state
   uiState: State.SQLite.clientDocument({
     name: 'uiState',
-    schema: Schema.Struct({ 
-      newTodoText: Schema.String, 
-      filter: Schema.Literal('all', 'active', 'completed') 
+    schema: Schema.Struct({
+      newTodoText: Schema.String,
+      filter: Schema.Literal('all', 'active', 'completed')
     }),
-    default: { 
-      id: SessionIdSymbol, 
-      value: { newTodoText: '', filter: 'all' } 
+    default: {
+      id: SessionIdSymbol,
+      value: { newTodoText: '', filter: 'all' }
     },
   }),
 }

package/docs/{reference/platform-adapters → platform-adapters}/cloudflare-durable-object-adapter/index.md

@@ -1,4 +1,4 @@
-# Cloudflare Durable Object Adapter
+# Cloudflare Durable Object adapter
 
 The Cloudflare Durable Object adapter enables running LiveStore applications on Cloudflare Workers with stateful Durable Objects for synchronized real-time data.
 
@@ -450,4 +450,4 @@ Resetting persistence deletes all LiveStore state and eventlog data stored insid
 - Subscribe to data changes inside the Durable Object to trigger side effects (see the client Durable Object example).
 - Wire additional routes in the worker fetch handler to expose debugging endpoints or admin operations.
 
-For sync backend-related APIs like `makeDurableObject`, `handleSyncRequest`, and `matchSyncRequest`, see the [Cloudflare sync provider documentation](/reference/syncing/sync-provider/cloudflare/).
+For sync backend-related APIs like `makeDurableObject`, `handleSyncRequest`, and `matchSyncRequest`, see the [Cloudflare sync provider documentation](/sync-providers/cloudflare).

package/docs/{reference/platform-adapters → platform-adapters}/electron-adapter/index.md

@@ -1,8 +1,8 @@
-# Electron Adapter
+# Electron adapter
 
 ## Using LiveStore with Electron
 
-LiveStore can already be used in Electron through the [web adapter](/reference/platform-adapters/web-adapter), which works perfectly fine for most use cases. The web adapter leverages the browser APIs available in Electron's renderer process, providing full LiveStore functionality including reactive queries, offline-first operation, and sync capabilities.
+LiveStore can already be used in Electron through the [web adapter](/platform-adapters/web-adapter), which works perfectly fine for most use cases. The web adapter leverages the browser APIs available in Electron's renderer process, providing full LiveStore functionality including reactive queries, offline-first operation, and sync capabilities.
 
 ## Native Electron Adapter
 

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

@@ -0,0 +1,262 @@
+# 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 a custom `useAppStore()` hook, then set up a `StoreRegistry` with `<StoreRegistryProvider>`:
+
+## `reference/platform-adapters/expo-adapter/usage.tsx`
+
+```tsx filename="reference/platform-adapters/expo-adapter/usage.tsx"
+
+const adapter = makePersistedAdapter()
+
+const useAppStore = () =>
+  useStore({
+    storeId: 'my-app',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+
+export const App = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <Suspense fallback={<Text>Loading...</Text>}>
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <TodoList />
+        </StoreRegistryProvider>
+      </Suspense>
+    </SafeAreaView>
+  )
+}
+
+const TodoList = () => {
+  const store = useAppStore()
+  const todos = store.useQuery(queryDb(tables.todos.select()))
+  return <Text>{todos.length} todos</Text>
+}
+```
+
+### `reference/platform-adapters/expo-adapter/schema.ts`
+
+```ts filename="reference/platform-adapters/expo-adapter/schema.ts"
+
+export 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 })
+```
+
+For more details on the registry, and hooks, 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: {
+    // Optional: custom base directory (defaults to expo-sqlite's default)
+    // directory: '/custom/path/to/databases',
+    subDirectory: 'my-app',
+  },
+})
+```
+
+### Available Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `storage.directory` | `string` | Base directory for database files (defaults to `expo-sqlite`'s default directory) |
+| `storage.subDirectory` | `string` | Subdirectory relative to `directory` 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/{reference/platform-adapters → platform-adapters}/node-adapter/index.md

@@ -1,4 +1,4 @@
-# Node Adapter
+# Node adapter
 
 Works with Node.js, Bun and Deno.
 

package/docs/{reference/platform-adapters → platform-adapters}/tauri-adapter/index.md

@@ -1,6 +1,6 @@
-# Tauri Adapter
+# Tauri adapter
 
-## Native 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.
 

package/docs/{reference/platform-adapters → platform-adapters}/web-adapter/index.md

@@ -1,4 +1,4 @@
-# Web Adapter
+# Web adapter
 
 ## Installation
 
@@ -149,6 +149,43 @@ During development (`NODE_ENV !== 'production'`), LiveStore automatically copies
 
 LiveStore also uses `window.sessionStorage` to retain the identity of a client session (e.g. tab/window) across reloads.
 
+### Private browsing mode
+
+In Safari and Firefox private browsing mode, OPFS is not available due to browser restrictions. When this happens, LiveStore automatically falls back to in-memory storage. This means:
+
+- The app will continue to work normally during the session
+- Data will not persist across page reloads or tab closures
+- Sync functionality (if configured) will still work
+
+You can detect when the store is running in-memory mode using `store.storageMode`:
+
+```tsx
+if (store.storageMode === 'in-memory') {
+  // Show a warning to the user
+  showToast('Data will not be saved in private browsing mode')
+}
+```
+
+The `storageMode` property returns:
+- `'persisted'`: Data is being persisted to disk (e.g., via OPFS)
+- `'in-memory'`: Data is only stored in memory and will be lost on page refresh
+
+You can also listen for boot status events including warnings using the `onBootStatus` callback in your store options:
+
+```ts
+const useAppStore = () => useStore({
+  storeId: 'app',
+  schema,
+  adapter,
+  batchUpdates: ReactDOM.unstable_batchedUpdates,
+  onBootStatus: (status) => {
+    if (status.stage === 'warning') {
+      console.warn(`Storage warning (${status.reason}): ${status.message}`)
+    }
+  },
+})
+```
+
 ### Resetting local persistence
 
 Resetting local persistence only clears data stored in the browser and does not affect any connected sync backend.
@@ -201,10 +238,42 @@ Assuming the web adapter in a multi-client, multi-tab browser application, a dia
 
 ## 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)).
+- Notable required browser APIs: OPFS, `navigator.locks`, WASM
+- SharedWorker is used for multi-tab synchronization but is not strictly required
+
+### Android Chrome (Single-tab mode)
+
+Android Chrome does not support the `SharedWorker` API ([Chromium bug #40290702](https://issues.chromium.org/issues/40290702)). When running on Android Chrome, LiveStore automatically falls back to **single-tab mode**:
+
+- Each browser tab runs independently with its own leader worker
+- Data is still persisted to OPFS (same as full mode)
+- Multi-tab synchronization is not available
+- Devtools are not supported in single-tab mode
+- A warning is logged to the console when this fallback occurs
+
+You can also explicitly use single-tab mode if you don't need multi-tab support:
+
+## `reference/platform-adapters/web-adapter/single-tab.ts`
+
+```ts filename="reference/platform-adapters/web-adapter/single-tab.ts"
+/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet keeps inline adapter */
+// ---cut---
+
+// Use this only if you specifically need single-tab mode.
+// Prefer makePersistedAdapter which auto-detects SharedWorker support.
+const adapter = makeSingleTabAdapter({
+  worker: LiveStoreWorker,
+  storage: { type: 'opfs' },
+})
+```
+
+:::note
+The single-tab adapter is intended as a fallback for browsers without SharedWorker support.
+We plan to remove it once SharedWorker is supported in Android Chrome.
+Track progress: [LiveStore #321](https://github.com/livestorejs/livestore/issues/321)
+:::
 
-## Best Practices
+## Best practices
 
 - It's recommended to develop in an incognito window to avoid issues with persistent storage (e.g. OPFS).