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

package/docs/overview/introduction/index.md

@@ -2,4 +2,412 @@
 
 ## What is LiveStore?
 
-TBD
+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/overview/why-livestore/index.md

@@ -1,5 +1,111 @@
 # Why LiveStore?
 
-## Why should you use LiveStore?
+## The problem LiveStore solves
 
-TBD
+Building modern apps with great UX means handling a lot of complexity:
+
+- **State management**: Keeping UI in sync with data
+- **Persistence**: Surviving refreshes and app restarts  
+- **Offline support**: Working without a network connection
+- **Real-time sync**: Reflecting changes across devices instantly
+- **Conflict resolution**: Handling concurrent edits gracefully
+
+Traditionally, each of these concerns requires separate solutions—a state library, local storage, a sync service, optimistic update logic, retry queues. These pieces don't naturally fit together, leading to complex, fragile code and subtle bugs.
+
+LiveStore provides a _unified architecture_ that handles all of these concerns through one coherent model: event sourcing.
+
+As a positive side-effect, the simplicity of LiveStore's event-driven abstractions also leads to a superior DX compared to the traditional ways of dealing with state.
+
+## What makes LiveStore different
+
+### A real database, not just a cache
+
+Most state management tools treat local data as a _cache_ of server state. This introduces complexity that's hard to manage due to the inherent intricacies of caching.
+
+LiveStore flips this: your local SQLite database is the primary data source, and the server is just a sync target to which data is distributed automatically.
+
+<SourceOfTruthDiagram class="my-8" />
+
+This means:
+- **No loading states for reads**—queries execute synchronously against local SQLite
+- **Full SQL power**—joins, aggregations, complex filters, all instant
+- **Offline by default**—your app works the same whether online or not
+
+### Events as the source of truth
+
+Instead of syncing mutable state (which leads to "who wins?" conflicts), LiveStore syncs an append-only log of events. This is fundamentally easier to reason about:
+
+- Events merge naturally—you're combining histories, not reconciling states
+- Every change is auditable—you have a complete record of what happened
+- State is always rebuildable—replay events to reconstruct any point in time
+
+### Sync that actually works
+
+LiveStore includes a battle-tested sync engine that handles the hard problems:
+
+- **Optimistic updates**: Changes appear instantly, sync happens in the background
+- **Automatic offline queue**: Events committed offline sync when connectivity returns  
+- **Deterministic conflict resolution**: Same events always produce the same state
+- **Pluggable backends**: Use Cloudflare, ElectricSQL, or build your own
+
+### Built for demanding apps
+
+LiveStore was developed as the foundation for [Overtone](https://overtone.pro), a professional music application requiring 120fps performance with complex, real-time collaborative state. It's designed for apps where performance and reliability aren't negotiable.
+
+### Open-source: By developers, for developers
+
+LiveStore is entirely open-source. There is no company behind it and it's only possible through its generous [sponsors](/sustainable-open-source/sponsoring).
+
+## LiveStore vs. the alternatives
+
+### vs. State management libraries (Redux, Zustand, MobX)
+
+These solve state management but not persistence or sync. You'll need to add:
+- Local storage or IndexedDB for persistence
+- A sync layer for real-time updates
+- Optimistic update logic
+- Offline queue management
+
+LiveStore handles all of this out of the box.
+
+### vs. Backend-as-a-Service (Firebase, Supabase)
+
+These provide sync but treat the server as the source of truth. The consequences are:
+- Reads require network round-trips (or complex caching)
+- Offline support is limited or requires significant extra work
+- You're locked into their data model and pricing
+
+LiveStore is client-first, works fully offline, and syncs via any backend you choose.
+
+### vs. Other local-first solutions (ElectricSQL, Zero, PowerSync)
+
+These are excellent if you have an existing Postgres database you want to sync to clients. LiveStore is better when:
+- You're building a new app without legacy data
+- You want event sourcing semantics (not just row-level sync)
+- You need the flexibility to materialize state in different ways
+
+See the [local-first landscape](https://localfirst.fm/landscape) for a comprehensive comparison.
+
+## A great developer experience (DX)
+
+LiveStore is designed to make the right thing easy:
+
+- **Type-safe schema**: Your events, tables, and queries are fully typed
+- **Reactive by default**: UI updates automatically when data changes
+- **Powerful devtools**: Inspect state, browse events, time-travel debug
+- **Cross-platform**: Same mental model on web, mobile, desktop, and server
+
+## When to choose LiveStore
+
+**Choose LiveStore if:**
+- You're building a new app that should work offline
+- You want a unified solution for state, persistence, and sync
+- Your app has complex local state that benefits from SQL queries
+- You value auditability and the ability to replay/debug state changes
+
+**Consider alternatives if:**
+- You need to sync with an existing server database
+- Your data won't fit in client memory
+- You're building a traditional request/response app without offline needs
+
+Still unsure? Try the [evaluation exercise](/overview/when-livestore#evaluation-exercise) to model your app's events and see if it feels natural.