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

package/docs/misc/troubleshooting/index.md

@@ -53,17 +53,17 @@ Note on terminology
 
 ### Query doesn't update properly
 
-If you notice the result of a `useQuery` hook is not updating properly, you might be missing some dependencies in the query's hash.
+If you notice the result of a `useQuery()` hook is not updating properly, you might be missing some dependencies in the query's hash.
 
 For example, the following query:
 
 ```ts
 // Don't do this
-const query$ = useQuery(queryDb(tables.issues.query.where({ id: issueId }).first()))
+const query$ = store.useQuery(queryDb(tables.issues.query.where({ id: issueId }).first()))
 //                                                              ^^^^^^^ missing in deps
 
 // Do this instead
-const query$ = useQuery(queryDb(tables.issues.query.where({ id: issueId }).first(), { deps: [issueId] }))
+const query$ = store.useQuery(queryDb(tables.issues.query.where({ id: issueId }).first(), { deps: [issueId] }))
 ```
 
 ## `node_modules` related issues

package/docs/{reference → overview}/concepts/index.md

@@ -18,22 +18,22 @@
     - Multiple sessions can exist within a single client (e.g., multiple browser tabs)
     - Store
     - Reactivity graph
-- [Devtools](/reference/devtools)
-- [Events](/reference/events)
+- [Devtools](/building-with-livestore/devtools)
+- [Events](/building-with-livestore/events)
   - Event definition
   - Eventlog
   - Synced vs client-only events
 - Framework integration
   - A framework integration is a package that provides a way to integrate LiveStore with a framework (e.g. React, Solid, Svelte, etc.)
-- [Reactivity system](/reference/reactivity-system)
+- [Reactivity system](/building-with-livestore/reactivity-system)
   - Db queries `queryDb()`
   - Computed queries `computed()`
   - Signals `signal()`
 - Schema
   - LiveStore uses schema definitions for the following cases:
-    - [Event definitions](/reference/events)
-    - [SQLite state schema](/reference/state/sqlite-schema)
-    - [Query result schemas](/reference/state/sql-queries)
+    - [Event definitions](/building-with-livestore/events)
+    - [SQLite state schema](/building-with-livestore/state/sqlite-schema)
+    - [Query result schemas](/building-with-livestore/state/sql-queries)
   - LiveStore uses the [Effect Schema module](/patterns/effect) to define fine-granular schemas
 - State
   - Derived from the eventlog via materializers
@@ -44,7 +44,7 @@
       - Used by the reactivity graph
     - Persisted SQLite database (usually running on the leader thread)
     - Fully derived from the eventlog
-- [Store](/reference/store)
+- [Store](/building-with-livestore/store)
   - A store exposes most of LiveStore's functionality to the application layer and is the main entry point for using LiveStore.
   - To create a store you need to provide a schema and a platform adapter which creates a client session.
   - A store is often created, managed and accessed through a framework integration (like React).
@@ -70,7 +70,7 @@ LiveStore is designed to be pluggable in various ways:
 - Sync providers
 - Framework integrations
 
-## Important Notes on Identity
+## Important notes on identity
 
 - LiveStore does not have built-in concepts of "users" or "devices"
 - User identity must be modeled within your application domain through events and application logic

package/docs/{evaluation → overview}/how-livestore-works/index.md

@@ -6,41 +6,41 @@ LiveStore uses event sourcing to sync events across clients and materialize stat
 
 <HowItWorksDiagram class="my-8" />
 
-## How LiveStore Works Client-Side
+## How LiveStore works client-side
 
 On the client, LiveStore provides a reactive SQLite database for application state, which is kept consistent through an underlying event sourcing mechanism.
 
-#### Local Reactive SQLite
+#### Local reactive SQLite
 
 Application state is materialized into a local SQLite database, offering high-performance, offline-capable data access. This SQLite database is reactive: UI components subscribe to data changes and update automatically when the state changes. LiveStore uses in-memory SQLite for sub-millisecond queries and persistent SQLite for durable storage across application sessions.
 
-#### Event Sourcing
+#### Event sourcing
 
 Underpinning the reactive state, LiveStore implements the event sourcing pattern. All data modifications are captured as an immutable, ordered sequence of events. This eventlog serves as the canonical history, enabling reliable state reconstruction and providing inherent auditability, which aids in debugging. The reactive SQLite state is a projection of this eventlog.
 
-#### Client-Side Event Flow
+#### Client-side event flow
 
 1.  **Event Committing:** User interactions within the application generate events detailing the specific action (e.g., `TodoCreated`, `TaskCompleted`).
 2.  **Local Persistence & Materialization:** The committed event is atomically persisted to the local eventlog and immediately materialized as state into the SQLite database.
 3.  **UI Reactivity:** Changes to the SQLite database trigger the reactivity system, causing subscribed UI components (e.g. React components) to automatically update and reflect the new state.
 
-## How LiveStore Syncing Works
+## How LiveStore syncing works
 
 LiveStore extends its local event-sourcing model globally by synchronizing events across all clients, typically through a central sync backend. This ensures that the eventlog, serving as the single source of truth, is consistently replicated, leading to an eventually consistent state for all participants.
 
-#### Push/Pull Event Synchronization
+#### Push/pull event synchronization
 
 Inspired by Git, LiveStore employs a push/pull model for event synchronization. Clients must first pull the latest events from the sync backend to ensure their local eventlog is up-to-date before they can push their own newly committed local events. This model helps maintain a global total order of events. Local pending events that haven't been pushed are rebased on top of the latest upstream events before being pushed.
 
-#### Sync Provider Integration
+#### Sync provider integration
 
 LiveStore supports various sync backend implementations, and it's straightforward for developers to create their own. The sync backend is responsible for storing events, enforcing the total event order, and notifying clients of new events.
 
-#### Conflict Resolution
+#### Conflict resolution
 
 When concurrent operations from different clients lead to conflicting events, LiveStore defaults to a "last-write-wins" strategy. However, it also provides the capability for developers to implement custom merge conflict resolution logic tailored to their application's specific needs.
 
-#### Overall Syncing Data Flow
+#### Overall syncing data flow
 
 After a local event is committed and materialized (as per the client-side flow), LiveStore attempts to push this event to the sync backend. Simultaneously, LiveStore is pulling events from the sync backend in the background.
 
@@ -51,6 +51,6 @@ Two main scenarios can occur during a push attempt:
 
 In both scenarios, once remote events are received (either through background pulling or during a push cycle), they are persisted to the local eventlog, materialized into the local SQLite database, and the UI reacts to the new state, ensuring eventual consistency.
 
-## Platform Adapters
+## Platform adapters
 
 LiveStore includes platform adapters to integrate with various environments, such as web browsers, mobile applications (iOS/Android), desktop applications, and Node.js.

package/docs/overview/introduction/index.md

@@ -0,0 +1,413 @@
+# Introduction
+
+## What is LiveStore?
+
+LiveStore is an event-driven data layer with a built-in sync engine. Its prime use case is building complex, client-side apps like [Linear](http://linear.app/), [Figma](https://www.figma.com/) or [Notion](https://notion.so/) that also work offline.
+
+Think of LiveStore as a next-generation state management library (like Zustand or Redux) that also persists and distributes state:
+
+<CapabilitiesDiagram class="my-8" />
+
+The combination of persisted and distributed state is a giant leap for creating an **amazing user experience** (UX), while also providing a **best-in-class developer experience** (DX). The **immutable eventlog** enables robust testing and tight feedback loops, making it perfect for agentic coding. 
+
+<div class="not-content grid grid-cols-1 md:grid-cols-3 gap-4 my-8">
+  <div class="rounded-xl border border-gray-700 p-5">
+    <h3 class="text-base font-medium !mt-0 !mb-2">UX</h3>
+    <ul class="!space-y-2 text-sm list-none p-0 m-0">
+      <li><strong>Synced</strong>: Real-time updates across devices</li>
+      <li><strong>Fast</strong>: No async loading over the network</li>
+      <li><strong>Persistent</strong>: Works offline, survives page refresh</li>
+    </ul>
+  </div>
+
+  <div class="rounded-xl border border-gray-700 p-5">
+    <h3 class="text-base font-medium !mt-0 !mb-2">DX</h3>
+    <ul class="!space-y-2 text-sm list-none p-0 m-0">
+      <li><strong>Principled</strong>: Event-driven instead of mutable state</li>
+      <li><strong>Composable & Type-safe</strong>: Fully typed events & queries</li>
+      <li><strong>Reactive</strong>: Automatic UI updates when data changes</li>
+    </ul>
+  </div>
+
+  <div class="rounded-xl border border-gray-700 p-5">
+    <h3 class="text-base font-medium !mt-0 !mb-2">AX</h3>
+    <ul class="!space-y-2 text-sm list-none p-0 m-0">
+      <li><strong>Testable</strong>: Immutable eventlog for feedback loop</li>
+      <li><strong>Debuggable</strong>: Same events always produce same state</li>
+      <li><strong>Evolvable</strong>: Reset & fork state for experiments</li>
+    </ul>
+  </div>
+</div>
+
+LiveStore works cross-platform and can be used for building UI apps (web, mobile, desktop, ...), agents, and any other software like CLIs, scripts or server-to-server applications.
+
+See this talk for more info: [Sync different: Event sourcing in local-first apps](https://www.youtube.com/watch?v=nyPl84BopKc&list=PL4isNRKAwz2MabH6AMhUz1yS3j1DqGdtT).
+
+<details>
+<summary>Are you an expert? See here for advanced topics.</summary>
+- [How LiveStore deals with merge conflicts?](/overview/how-livestore-works#conflict-resolution)
+- Why event-sourcing instead of CRDTs or query-driven sync?
+- How do schema migrations work?
+- What are limitations of LiveStore?
+- How LiveStore is perfect for coding agents.
+</details>
+
+## The core idea: Synced events -> State -> UI
+
+Unlike other sync solutions, LiveStore syncs events—not state!
+
+Events are immutable facts that describe what happened ("TodoCreated", "TodoCompleted"), while state is derived by replaying them. This means every client reconstructs the same state from the same event history, making sync predictable and debuggable.
+
+The state then changes trigger reaactive UI updates.
+
+### Traditional state management uses ephemeral, in-memory state
+
+Traditional state management works like this: you dispatch actions that update an in-memory store, and your UI reacts to changes. But that state vanishes when the user refreshes or closes the browser. Add persistence and you need to manage local storage which essentially serves as a secondary database to the data you've stored in the cloud. Add sync and you're dealing with conflict resolution, offline queues, and backend integration. LiveStore handles all this for you with one simple, event-driven API!
+
+### LiveStore persists events which materialize into state
+
+LiveStore handles all of this through one unified pattern: **event sourcing**.
+
+<div class="d2-full-width">
+
+```d2
+...@../../../../src/content/base.d2
+
+direction: right
+
+"User action": {
+  label: "User action"
+  shape: rectangle
+}
+
+Event: {
+  label: "Event"
+  shape: rectangle
+}
+
+Eventlog: {
+  label: "Eventlog"
+  shape: rectangle
+}
+
+"SQLite state": {
+  label: "SQLite state"
+  shape: rectangle
+}
+
+UI: {
+  label: "UI"
+  shape: rectangle
+}
+
+"Sync to other clients": {
+  label: "Sync to other clients"
+  shape: rectangle
+}
+
+"User action" -> Event -> Eventlog -> "SQLite state" -> UI
+Eventlog -> "Sync to other clients"
+```
+
+</div>
+
+Instead of mutating state directly, you commit **events** that _describe_ what happened. These events are persisted to an **eventlog** (like a git history) and automatically materialized into a local **SQLite database** that your UI queries reactively.
+
+:::note
+While the majority of apps will probably use SQLite as the data store for persistence, LiveStore is flexible enough to materialize state into other targets as well (e.g. file systems).
+:::
+
+If you want to learn more, you can dive deeper into [how LiveStore works](/overview/how-livestore-works).
+
+### Comparison with traditional state management like Redux
+
+If you've used Redux, this pattern of "comitting events" will feel familiar: **Events are like actions, materializers are like reducers, and the SQLite state is like your store.**
+
+But there are key differences:
+
+| Redux                                              | LiveStore                                   |
+| -------------------------------------------------- | ------------------------------------------- |
+| Actions dispatch → reducers update in-memory state | Events commit → materializers update SQLite |
+| State lost on refresh                              | Events persisted locally                    |
+| Sync requires external setup                       | Sync built-in via eventlog                  |
+| Fixed state shape                                  | Query any shape with SQL                    |
+
+## A practical example
+
+Let's walk through a simple example of a todo list with LiveStore and React.
+
+### Define your schema
+
+At the core of every app built with LiveStore, you have a _schema_ which consists of three parts:
+
+- **Events**: describe what can happen in your app
+- **State**: defines how data is stored in your app
+- **Materializers**: determines how events are mapped to state in your app
+
+Here's an example:
+
+## `reference/overview/introduction/schema.ts`
+
+```ts filename="reference/overview/introduction/schema.ts"
+// schema.ts
+
+// 1. Define events (the things that can happen in your app)
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+    }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: Schema.String }),
+  }),
+}
+
+// 2. Define SQLite tables (how to query your state)
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text({ default: '' }),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+}
+
+// 3. Define materializers (how to turn events into state)
+const materializers = State.SQLite.materializers(events, {
+  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text }),
+  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+export const schema = makeSchema({ events, state })
+```
+
+### Usage on the frontend
+
+LiveStore comes with integrations for all major frontend frameworks, e.g. for [React](/framework-integrations/react-integration) or [Vue](/framework-integrations/vue-integration).
+
+The [`queryDb`](/building-with-livestore/reactivity-system#reactive-sql-queries) function creates a [reactive query](/building-with-livestore/reactivity-system) which updates automatically when its data in the database changes. Here's how to use it in React:
+
+## `reference/overview/introduction/todo-app.tsx`
+
+```tsx filename="reference/overview/introduction/todo-app.tsx"
+// TodoApp.tsx
+
+const adapter = makeInMemoryAdapter()
+
+const useAppStore = () =>
+  useStore({
+    storeId: 'my-app',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+
+// Define a reactive query
+const visibleTodos$ = queryDb(() => tables.todos, {
+  label: 'visibleTodos',
+})
+
+export function TodoApp() {
+  const store = useAppStore()
+
+  // Reactively updates when todos change in the DB
+  const todos = store.useQuery(visibleTodos$)
+
+  const addTodo = (text: string) => {
+    // Commit an event to the store
+    store.commit(
+      events.todoCreated({
+        id: crypto.randomUUID(),
+        text,
+      }),
+    )
+  }
+
+  const completeTodo = (id: string) => {
+    // Commit an event to the store
+    store.commit(events.todoCompleted({ id }))
+  }
+
+  return (
+    <div>
+      <button type="button" onClick={() => addTodo('New todo')}>
+        Add
+      </button>
+      {todos.map((todo) => (
+        <button key={todo.id} type="button" onClick={() => completeTodo(todo.id)}>
+          {todo.completed ? '✓' : '○'} {todo.text}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+### `reference/overview/introduction/schema.ts`
+
+```ts filename="reference/overview/introduction/schema.ts"
+// schema.ts
+
+// 1. Define events (the things that can happen in your app)
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+    }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: Schema.String }),
+  }),
+}
+
+// 2. Define SQLite tables (how to query your state)
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text({ default: '' }),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+}
+
+// 3. Define materializers (how to turn events into state)
+const materializers = State.SQLite.materializers(events, {
+  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text }),
+  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+export const schema = makeSchema({ events, state })
+```
+
+This code replaces all the API calls, state management, UI update, caching, and synchronization logic you may be used to from writing apps in a more traditional way. If configured, it also automatically takes care of syncing data to other clients.
+
+Also notice how there's no loading state for queries—SQLite runs in-memory on the main thread, so reads are synchronous and instant, making your app super snappy and reactive to user input.
+
+## Why events?
+
+But why use events at all, rather than directly mutating state?
+
+### Benefits of using events for state management
+
+- **Events capture intent, not just outcome.** When you mutate state directly (`todo.completed = true`), you lose the _why_. Events like `TodoCompleted` preserve the user's intent, which matters for debugging, analytics, undo/redo, and features like activity feeds.
+- **Events decouple what happened from how it's stored.** Your state shape can evolve independently of your event history. Need a new denormalized table for performance? Just add a materializer—no data migration required.
+- **Events make sync tractable.** Syncing mutable state across devices is hard (which field wins?). Syncing an append-only event log is simpler: you're merging histories, not reconciling conflicting states.
+
+### Benefits of LiveStore's eventlog 
+
+The [eventlog](/building-with-livestore/events/#eventlog) sits the core of LiveStore and gives you several benefits:
+
+- **Persistence**: Events survive page refreshes and app restarts
+- **Sync**: Events replay identically across devices
+- **History**: Full audit trail of every change (enables time travel and helps with debugging)
+- **Flexibility**: Change your queries without migrations—just materialize differently
+
+## How syncing works
+
+LiveStore includes a **sync engine** which handles [syncing](/building-with-livestore/syncing) for you under the hood. 
+
+When you can enable syncing, the sync engine distributes your state across various other clients (these can be other browsers, apps, devices, servers—anything that can connect to your store via an [adapter](/overview/how-livestore-works#platform-adapters)).
+
+LiveStore uses a push/pull model inspired by git:
+
+1. Local events are committed immediately (optimistic updates by default)
+1. Events sync to a central backend when online
+1. Other clients pull new events and materialize them locally
+1. Conflicts resolve deterministically (last-write-wins by default, or custom logic)
+
+Here's an example that syncs your state via Cloudflare (using the [`@livestore/sync-cf`](/sync-providers/cloudflare/) package):
+
+## `reference/overview/introduction/worker.ts`
+
+```ts filename="reference/overview/introduction/worker.ts"
+
+makeWorker({
+  schema,
+  sync: {
+    backend: makeWsSync({ url: `${location.origin}/sync` }),
+  },
+})
+```
+
+### `reference/overview/introduction/schema.ts`
+
+```ts filename="reference/overview/introduction/schema.ts"
+// schema.ts
+
+// 1. Define events (the things that can happen in your app)
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+    }),
+  }),
+  todoCompleted: Events.synced({
+    name: 'v1.TodoCompleted',
+    schema: Schema.Struct({ id: Schema.String }),
+  }),
+}
+
+// 2. Define SQLite tables (how to query your state)
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text({ default: '' }),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+}
+
+// 3. Define materializers (how to turn events into state)
+const materializers = State.SQLite.materializers(events, {
+  'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text }),
+  'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+export const schema = makeSchema({ events, state })
+```
+
+That's all the configuration needed—your app works offline automatically. When connectivity returns, LiveStore syncs pending events and reconciles state.
+
+## When LiveStore fits
+
+LiveStore works well for:
+
+- **Productivity apps** (todo lists, note-taking, project management, ...)
+- **Collaborative tools** with multi-player support
+- **Apps with complex local state** that need SQL-level queries
+- **Local-first** apps with offline support
+- **Cross-platform apps** (web, mobile, desktop, server)
+- ... or any combination of the above
+
+LiveStore may not fit if:
+
+- Your data must live on an existing server database (consider [ElectricSQL](https://electric-sql.com) or [Zero](https://zero.rocicorp.dev))
+- You're building a traditional client-server app without offline needs
+- You need unbounded data that won't fit in client memory
+
+If you're unsure, go through our [evaluation exercise](/overview/when-livestore) to find out whether LiveStore is a good fit for your project or [compare it with similar tools](/overview/technology-comparison).
+
+## Next steps
+
+- [Tutorial](/tutorial/0-welcome) — Step-by-step tutorial introducing the main concepts and workflows of LiveStore
+- [Getting started with React](/getting-started/react-web) — Quickstart to set up a React app
+- [How LiveStore works](/overview/how-livestore-works) — Deeper dive into the LiveStore architecture
+- [Examples](/examples) — See LiveStore in action with TodoMVC, Linearlite, and more

package/docs/{evaluation → overview}/technology-comparison/index.md

@@ -19,13 +19,13 @@ LiveStore shares a lot of similarities with Redux in that sense that both are ba
   - A major difference here is that LiveStore's state materialized as a SQLite database allows for a lot more flexibility via dynamic queries and aggregations vs Redux's static views.
 - Redux reducers are similar to LiveStore's materializers: Both are used to transform events/actions into a final state.
 - Both Redux and LiveStore are client-centric.
-- Both Redux and LiveStore provide powerful [devtools](/reference/devtools).
+- Both Redux and LiveStore provide powerful [devtools](/building-with-livestore/devtools).
 
 While LiveStore can be used for the same use cases as Redux, LiveStore goes far beyond Redux in the following ways:
 
 - LiveStore leverages SQLite for a more powerful state model allowing for flexible queries and aggregations with much simpler materialization logic.
 - LiveStore supports client-persistence out of the box.
-- LiveStore comes with a built-in [sync engine](/reference/syncing) syncing events between clients.
+- LiveStore comes with a built-in [sync engine](/building-with-livestore/syncing) syncing events between clients.
 
 As a downside compared to Redux, LiveStore has a slightly larger bundle size.
 

package/docs/{evaluation → overview}/when-livestore/index.md

@@ -3,9 +3,9 @@
 Choosing a data layer for a local-first app is a big decision and should be considered carefully.  On a high level, LiveStore can be a good fit if ...
 - you are looking for a principled data layer that works across platforms
 - you want to use SQLite for your queries
-- you like [event sourcing](/evaluation/event-sourcing) to model data changes
+- you like [event sourcing](/understanding-livestore/event-sourcing) to model data changes
 - you are working on a new app as LiveStore doesn't yet provide a way to [re-use an existing database](/misc/faq#existing-database)
-- the current [state of the project](/evaluation/state-of-the-project) aligns with your own timeline and requirements
+- the current [state of the project](/misc/state-of-the-project) aligns with your own timeline and requirements
 
 ## Evaluation exercise