-
toggleTodo(todo)} />
)}
{value}
}
```
#### Solid
## `reference/reactivity-system/solid-component.tsx`
```tsx filename="reference/reactivity-system/solid-component.tsx"
declare const state$: LiveQueryDef{value()}
}
```
### Reacting to changing variables passed to queries
If your query depends on a variable passed in by the component, use the deps array to react to changes in this variable.
## `reference/reactivity-system/deps-query.tsx`
```tsx filename="reference/reactivity-system/deps-query.tsx"
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
declare const store: Store & ReactApi
export const todos$ = ({ showCompleted }: { showCompleted: boolean }) =>
queryDb(
() => {
return tables.todos.where(showCompleted ? { completed: true } : {})
},
{
label: 'todos$',
deps: [showCompleted ? 'true' : 'false'],
},
)
export const MyComponent: FC<{ showCompleted: boolean }> = ({ showCompleted }) => {
const todos = store.useQuery(todos$({ showCompleted })) as ReadonlyArray<{
id: string
text: string
completed: boolean
}>
return {todos.length} Done
}
```
## Further reading
- [Riffle](https://riffle.systems/essays/prelude/): Building data-centric apps with a reactive relational database
- [Adapton](http://adapton.org/) / [miniAdapton](https://arxiv.org/pdf/1609.05337)
## Related technologies
- [Signia](https://signia.tldraw.dev/): Signia is a minimal, fast, and scalable signals library for TypeScript developed by TLDraw.
# [Rules for AI agents](https://dev.docs.livestore.dev/building-with-livestore/rules-for-ai-agents/)
## AGENTS.md
Add the content of this `AGENTS.md` file or other custom rules:
```md wrap
- When you need to look up information about LiveStore, always use the `docs` directory that's shipped as part of the `@livestore/livestore` package in `node_modules/@livestore/livestore/docs`.
```
# [Syncing](https://dev.docs.livestore.dev/building-with-livestore/syncing/)
## How it works
LiveStore is based on [the idea of event-sourcing](/understanding-livestore/event-sourcing) which means it syncs events across clients (via a central sync backend) and then materializes the events in the local SQLite database. This means LiveStore isn't syncing the SQLite database itself directly but only the events that are used to materialize the database making sure it's kept in sync across clients.
The syncing mechanism is similar to how Git works in that regard that it's based on a "push/pull" model. Upstream events always need to be pulled before a client can push its own events to preserve a [global total order of events](https://medium.com/baseds/ordering-distributed-events-29c1dd9d1eff). Local pending events which haven't been pushed yet need to be rebased on top of the latest upstream events before they can be pushed.
## Events
A LiveStore event consists of the following data:
- `seqNum`: event sequence number
- `parentSeqNum`: parent event sequence number
- `name`: event name (refers to a event definition in the schema)
- `args`: event arguments (encoded using the event's schema definition, usually JSON)
### Event sequence numbers
- Event sequence numbers: monotonically increasing integers
- client event sequence number to sync across client sessions (never exposed to the sync backend)
### Sync heads
- The latest event in a eventlog is referred to as the "head" (similar to how Git refers to the latest commit as the "head").
- Given that LiveStore does hierarchical syncing between the client session, the client leader and the sync backend, there are three heads (i.e. the client session head, the client leader head, and the sync backend head).
## Sync backend
The sync backend acts as the global authority and determines the total order of events ("causality"). It's responsible for storing and querying events and for notifying clients when new events are available.
### Requirements for sync backend
- Needs to provide an efficient way to query an ordered list of events given a starting event ID (often referred to as cursor).
- Ideally provides a "reactivity" mechanism to notify clients when new events are available (e.g. via WebSocket, HTTP long-polling, etc).
- Alternatively, the client can periodically query for new events which is less efficient.
## Clients
- Each client initially chooses a random `clientId` as its globally unique ID
- LiveStore uses a 6-char nanoid
- In the unlikely event of a collision which is detected by the sync backend the first time a client tries to push, the client chooses a new random `clientId`, patches the local events with the new `clientId`, and tries again.
### Client sessions
- Each client has at least one client session
- Client sessions within the same client share local data
- In web adapters: multiple tabs/windows can be different sessions within the same client
- Sessions are identified by a `sessionId` which can persist (e.g., across tab reloads in web)
- For adapters which support multiple client sessions (e.g. web), LiveStore also supports local syncing across client sessions (e.g. across browser tabs or worker threads)
- Client session events are not synced to the sync backend
## Auth (authentication & authorization)
- TODO
- Provide basic example
- Encryption
## Advanced
### Sequence diagrams
#### Pulling events (without unpushed events)
```d2
...@../../../../src/content/base.d2
shape: sequence_diagram
Client: {
label: "Client"
}
SyncBackend: {
label: "Sync Backend"
}
Client -> SyncBackend: "`pull` request\n(head_cursor)"
SyncBackend -> SyncBackend: "Get new events\n(since head_cursor)"
SyncBackend -> Client: "New events"
Client -> Client: "Client is in sync"
```
#### Pushing events
```d2
...@../../../../src/content/base.d2
shape: sequence_diagram
Client: {
label: "Client"
}
SyncBackend: {
label: "Sync Backend"
}
Client -> Client: "Commit events"
Client -> SyncBackend: "`push` request\n(new_local_events)"
SyncBackend -> SyncBackend: "Validate & persist"
SyncBackend -> Client: "Push success"
Client -> Client: "Client is in sync"
```
### Rebasing
### Merge conflicts
- Merge conflict handling isn't implemented yet (see [this issue](https://github.com/livestorejs/livestore/issues/253)).
- Merge conflict detection and resolution will be based on the upcoming [facts system functionality](https://github.com/livestorejs/livestore/issues/254).
### Compaction
- Compaction isn't implemented yet (see [this issue](https://github.com/livestorejs/livestore/issues/136))
- Compaction will be based on the upcoming [facts system functionality](https://github.com/livestorejs/livestore/issues/254).
### Partitioning
- Currently LiveStore assumes a 1:1 mapping between an eventlog and a SQLite database.
- In the future, LiveStore aims to support multiple eventlogs (see [this issue](https://github.com/livestorejs/livestore/issues/255)).
## Design decisions / trade-offs
- Require a central sync backend to enforce a global total order of events.
- This means LiveStore can't be used in a fully decentralized/P2P manner.
- Do rebasing on the client side (instead of on the sync backend). This allows the user to have more control over the rebase process.
## Notes
- Rich text data is best handled via CRDTs (see [#263](https://github.com/livestorejs/livestore/issues/263))
## Further reading
- Distributed Systems lecture series by Martin Kleppmann: [YouTube playlist](https://www.youtube.com/playlist?list=PLeKd45zvjcDFUEv_ohr_HdUFe97RItdiB) / [lecture notes](https://www.cl.cam.ac.uk/teaching/2122/ConcDisSys/dist-sys-notes.pdf)
# [Store](https://dev.docs.livestore.dev/building-with-livestore/store/)
The `Store` is the most common way to interact with LiveStore from your application code. It provides a way to query data, commit events, and subscribe to data changes.
## Creating a store
For how to create a store in React, see the [React integration docs](/framework-integrations/react-integration). The following example shows how to create a store manually:
## `reference/store/create-store.ts`
```ts filename="reference/store/create-store.ts"
const adapter = makeAdapter({
storage: { type: 'fs' },
// sync: { backend: makeWsSync({ url: '...' }) },
})
export const bootstrap = async () => {
const store = await createStorePromise({
schema,
adapter,
storeId: 'some-store-id',
})
return store
}
```
### `reference/store/schema.ts`
```ts filename="reference/store/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 })
export const storeTables = tables
export const storeEvents = events
```
## Using a store
### Querying data
## `reference/store/query-data.ts`
```ts filename="reference/store/query-data.ts"
/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet shows query result */
// ---cut---
declare const store: Store
const todos = store.query(storeTables.todos)
console.log(todos)
```
### Subscribing to data
## `reference/store/subscribe.ts`
```ts filename="reference/store/subscribe.ts"
declare const store: Store
const unsubscribe = store.subscribe(storeTables.todos, (todos) => {
console.log(todos)
})
unsubscribe()
```
### Committing events
## `reference/store/commit-event.ts`
```ts filename="reference/store/commit-event.ts"
declare const store: Store
store.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))
```
### Streaming events
Currently only events confirmed by the sync backend are supported.
## `reference/store/stream-events.ts`
```ts filename="reference/store/stream-events.ts"
declare const store: Store
// Run once
for await (const event of store.events()) {
console.log('event from leader', event)
}
// Continuos stream
const iterator = store.events()[Symbol.asyncIterator]()
try {
while (true) {
const { value, done } = await iterator.next()
if (done) break
console.log('event from stream:', value)
}
} finally {
await iterator.return?.()
}
```
### Shutting down a store
LiveStore provides two APIs for shutting down a store:
## `reference/store/shutdown.ts`
```ts filename="reference/store/shutdown.ts"
/** biome-ignore-all lint/correctness/noUnusedVariables: docs snippet demonstrates shutdown helpers */
// ---cut---
declare const store: Store
const effectShutdown = Effect.gen(function* () {
yield* Effect.log('Shutting down store')
yield* store.shutdown()
})
const shutdownWithPromise = async () => {
await store.shutdownPromise()
}
```
## Effect integration
For applications using [Effect](https://effect.website), LiveStore provides a type-safe way to access stores through the Effect layer system via `makeStoreContext()`.
### Creating a typed store context
Use `makeStoreContext()` to create a typed context that preserves your schema types:
## `reference/store/effect/make-store-context.ts`
```ts filename="reference/store/effect/make-store-context.ts"
// ---cut---
// Define a typed store context with your schema
export const TodoStore = Store.Tag(schema, 'todos')
// Create a layer to initialize the store
const adapter = makeAdapter({ storage: { type: 'fs' } })
export const TodoStoreLayer = TodoStore.layer({
adapter,
batchUpdates: (cb) => cb(), // For Node.js; use React's unstable_batchedUpdates in React apps
})
```
### `reference/store/effect/schema.ts`
```ts filename="reference/store/effect/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 }),
}),
todoCompleted: Events.synced({
name: 'v1.TodoCompleted',
schema: Schema.Struct({ id: 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 }),
),
[events.todoCompleted.name]: defineMaterializer(events.todoCompleted, ({ id }) =>
tables.todos.update({ completed: true }).where({ id }),
),
})
const state = State.SQLite.makeState({ tables, materializers })
export const schema = makeSchema({ events, state })
export const storeTables = tables
export const storeEvents = events
```
The factory takes your schema type as a generic parameter and returns a `StoreContext` with:
- `Tag` - Context tag for dependency injection
- `Layer` - Creates a layer that initializes the store
- `DeferredTag` - For async initialization patterns
- `DeferredLayer` - Layer providing the deferred context
- `fromDeferred` - Layer that waits for deferred initialization
### Using the store in Effect services
Access the store in Effect code with full type safety and autocomplete:
## `reference/store/effect/usage-in-service.ts`
```ts filename="reference/store/effect/usage-in-service.ts"
// ---cut---
// Access the store in Effect code with full type safety
const _todoService = Effect.gen(function* () {
// Yield the store directly (it's a Context.Tag)
const { store } = yield* TodoStore
// Query with autocomplete for tables
const todos = store.query(storeTables.todos.select())
// Commit events
store.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))
return todos
})
// Or use static accessors for a more functional style
const _todoServiceAlt = Effect.gen(function* () {
// Query using static accessor
const todos = yield* TodoStore.query(storeTables.todos.select())
// Commit using static accessor
yield* TodoStore.commit(storeEvents.todoCreated({ id: '1', text: 'Buy milk' }))
return todos
})
```
### Layer composition
Compose store layers with your application services:
## `reference/store/effect/layer-composition.ts`
```ts filename="reference/store/effect/layer-composition.ts"
// ---cut---
// Define services that depend on the store
class TodoService extends Effect.Service{issue?.title}
}
```
### `reference/framework-integrations/react/multi-store/schema.ts`
```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
// Event definitions
export const events = {
issueCreated: Events.synced({
name: 'v1.IssueCreated',
schema: Schema.Struct({
id: Schema.String,
title: Schema.String,
status: Schema.Literal('todo', 'done'),
}),
}),
issueStatusChanged: Events.synced({
name: 'v1.IssueStatusChanged',
schema: Schema.Struct({
id: Schema.String,
status: Schema.Literal('todo', 'done'),
}),
}),
}
// State definition
export const tables = {
issue: State.SQLite.table({
name: 'issue',
columns: {
id: State.SQLite.text({ primaryKey: true }),
title: State.SQLite.text(),
status: State.SQLite.text(),
},
}),
}
const materializers = State.SQLite.materializers(events, {
'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
})
const state = State.SQLite.makeState({ tables, materializers })
export const schema = makeSchema({ events, state })
```
## Setting Up
### 1. Configure the Store
Create a store configuration file that exports a custom hook wrapping [`useStore()`](#usestoreoptions):
## `reference/framework-integrations/react/store.ts`
```ts filename="reference/framework-integrations/react/store.ts"
const adapter = makeInMemoryAdapter()
export const useAppStore = () =>
useStore({
storeId: 'app-root',
schema,
adapter,
batchUpdates,
})
```
The [`useStore()`](#usestoreoptions) hook accepts store configuration options and returns a store instance. It suspends while the store is loading, so components using it need to be wrapped in a `Suspense` boundary.
### 2. Set Up the Registry
Create a [`StoreRegistry`](#new-storeregistryconfig) and provide it via [`...
}
```
## Querying Data
Use [`store.useQuery()`](#storeusequeryqueryable) to subscribe to reactive queries:
## `reference/framework-integrations/react/use-query.tsx`
```tsx filename="reference/framework-integrations/react/use-query.tsx"
const query$ = queryDb(tables.todos.where({ completed: true }).orderBy('id', 'desc'), {
label: 'completedTodos',
})
export const CompletedTodos: FC = () => {
const store = useAppStore()
const todos = store.useQuery(query$)
return (
{todos.map((todo) => (
)
}
```
## Client Documents
Use [`store.useClientDocument()`](#storeuseclientdocumenttable-id-options) for client-specific state:
## `reference/framework-integrations/react/use-client-document.tsx`
```tsx filename="reference/framework-integrations/react/use-client-document.tsx"
export const TodoItem: FC<{ id: string }> = ({ id }) => {
const store = useAppStore()
const [todo, updateTodo] = store.useClientDocument(tables.uiState, id)
return (
)
}
```
## Advanced Patterns
### Multiple Stores
You can have multiple stores within a single React application. This is useful for:
- **Partial data synchronization** - Load only the data you need, when you need it
- **Multi-tenant applications** - Separate stores for each workspace, organization, or team (like Slack workspaces or Linear teams)
Use the [`storeOptions()`](#storeoptionsoptions) helper for type-safe, reusable configurations, and then create multiple instances for the same store configuration by using different `storeId` values:
## `reference/framework-integrations/react/multi-store/store.ts`
```ts filename="reference/framework-integrations/react/multi-store/store.ts"
// Define reusable store configuration with storeOptions()
// This helper provides type safety and can be reused across your app
export const issueStoreOptions = (issueId: string) =>
storeOptions({
storeId: `issue-${issueId}`,
schema,
adapter: makeInMemoryAdapter(),
})
```
## `reference/framework-integrations/react/multi-store/IssueView.tsx`
```tsx filename="reference/framework-integrations/react/multi-store/IssueView.tsx"
export function IssueView({ issueId }: { issueId: string }) {
// useStore() suspends the component until the store is loaded
// If the same store was already loaded, it returns immediately
const issueStore = useStore(issueStoreOptions(issueId))
// Query data from the store
const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
if (!issue) return {todo.text}
))}
Issue not found
return (
{issue.title}
Status: {issue.status}
{!showIssue ? (
) : (
Error loading issue
}>
-
{#each store.query(todos$) as todo (todo.id)}
- {todo.text} {/each}
Loading LiveStore...
- {{ todo.text }}
Loading LiveStore...
- {{ todo.text }}
{/* Your app components go here */}
TodoMVC
updateNewTodoText(e.target.value)} onKeyDown={(e) => { if (e.key === 'Enter') { createTodo() } }} />-
{visibleTodos.map((todo) => (
-
toggleTodo(todo)} />
))}
| Dark PNG | Dark SVG | Light PNG | Light SVG |
|---|---|---|---|
|
|
|
|
UX
- Synced: Real-time updates across devices
- Fast: No async loading over the network
- Persistent: Works offline, survives page refresh
DX
- Principled: Event-driven instead of mutable state
- Composable & Type-safe: Fully typed events & queries
- Reactive: Automatic UI updates when data changes
AX
- Testable: Immutable eventlog for feedback loop
- Debuggable: Same events always produce same state
- Evolvable: Reset & fork state for experiments
Are you an expert? See here for advanced topics.
- [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.
```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"
```
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 (
{todos.map((todo) => (
))}
)
}
```
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` }),
},
})
```
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
# [Technology comparison](https://dev.docs.livestore.dev/overview/technology-comparison/)
## TLDR of what sets LiveStore apart
- Uses combination of reactive, in-memory + synced, persisted SQLite for instant, synchronous queries
- Based on event-sourcing methodologies
- Client-centric (with great devtools)
## Other local-first/syncing technologies
To compare LiveStore with other local-first/syncing technologies, please see the [Local-First Landscape](https://www.localfirst.fm/landscape) resource.
## LiveStore vs Redux
LiveStore shares a lot of similarities with Redux in that sense that both are based on event-sourcing methodologies. Let's compare some of the core concepts:
- Redux actions are similar to LiveStore events: Both are used to describe "things that have happened"
- Redux views are similar to LiveStore's state (e.g. SQLite tables): Both are derived from the history of events/actions.
- 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](/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](/building-with-livestore/syncing) syncing events between clients.
As a downside compared to Redux, LiveStore has a slightly larger bundle size.
## Other state management libraries
- Zustand
- Redux Toolkit (RTK)
- MobX
- Jotai
- Xstate
- Recoil
- TanStack Query
# [When to use LiveStore (and when not)](https://dev.docs.livestore.dev/overview/when-livestore/)
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](/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](/misc/state-of-the-project) aligns with your own timeline and requirements
## Evaluation exercise
A great way to evaluate whether LiveStore is a good fit for your application, is by trying to model your application events (and optionally state) schema. This exercise can be done in a few minutes and can give you a good indication of whether LiveStore is a good fit for your application.
### Example: Calendar/scheduling app
Let's say you are building a calendar/scheduling app, your events might include:
- `AppointmentScheduled`
- `AppointmentRescheduled`
- `AppointmentCancelled`
- `ParticipantInvitedToAppointment`
- `ParticipantRespondedToInvite`
From this you might want to derive the following state (modeled as SQLite tables):
- `Appointment`
- `id`
- `title`
- `description`
- `participants`
- `Participant`
- `id`
- `name`
- `email`
## Great use cases for LiveStore
- High-performance desktop/web/mobile apps
- e.g. productivity apps like
- AI agents
- Apps that need ...
- solid offline support
- audit logs
## Benefits of LiveStore
- Unified data layer combining local reactive state with globally synced data
- Easy to ...
- reason about
- debug
- test
- evolve
- operate
## Reasons when not to use LiveStore
- You have an existing database which is the source of truth of your data. (Better use [Zero](https://zero.rocicorp.dev) or [ElectricSQL](https://www.electricsql.com) for this.)
- Your app data is highly connected across users (like a social network / marketplace / etc.) or modeling your data via read-write model separation/event sourcing doesn't seem feasible.
- You want to build a more traditional client-server application with your primary data source being a remote server.
- You want a full-stack batteries-included solution (e.g. auth, storage, etc.). (Technologies like [Jazz](https://jazz.tools) or [Instant](https://instantdb.com) might be a better fit.)
- You don't like to model your data via read-write model separation/event sourcing or the trade-offs it involves.
- You're a new developer and are just getting started. LiveStore is a relatively advanced technology with many design trade-offs that might make most sense after you have already experienced some of the problems LiveStore is trying to solve.
- You want to keep your app bundle size as small as possible. LiveStore adds a few hundred kB to your app bundle size (mostly due to bundling SQLite).
## Considerations
### Database constraints
- All the client app data should fit into a in-memory SQLite database
- Depending on the target device having databases up to 1GB in size should be okay.
- If you you have more data, you can consider segmenting your database into multiple SQLite database (e.g. segmented per project, workspace, document, ...).
- You can either use the `storeId` option for the segmentation or there could also be a way to use the [SQLite attach feature](https://www.sqlite.org/lang_attach.html) to dynamically attach/detach databases.
### Syncing
LiveStore's syncing system is designed for small/medium-level concurrency scenarios (e.g. 10s / low 100s of users collaborating on the same thing for a given eventlog).
- Collaboration on multiple different eventlogs concurrently is supported and should be used to "scale horizontally".
### Other considerations
- How data flows / what's the source of truth?
# [Why LiveStore?](https://dev.docs.livestore.dev/overview/why-livestore/)
## The problem LiveStore solves
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.
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.
# [Anonymous user transition](https://dev.docs.livestore.dev/patterns/anonymous-user-transition/)
## Basic idea
- Locally choose a unique identifier for the user (e.g. via `crypto.randomUUID()`).
- You might want to handle the very unlikely case that the identifier is not unique (collision) on the sync backend.
- Persist this identifier locally (either via a separate LiveStore instance or via `localStorage`).
- Use this identifier in the `storeId` for the user-related LiveStore instance.
- Initially when the user is anonymous, the store won't be synced yet (i.e. no sync backend used in adapter).
- As part of the auth flow, the LiveStore instance is now synced with the same `storeId` to a sync backend which will sync all local events to the sync backend making sure the user keeps all their data.
# [Auth](https://dev.docs.livestore.dev/patterns/auth/)
LiveStore doesn't include built-in authentication or authorization support, but you can implement it in your app's logic.
## Pass an auth payload to the sync backend
Use the `syncPayload` store option to send a custom payload to your sync backend.
### Example
The following example sends the authenticated user's JWT to the server.
## `patterns/auth/store-with-auth.tsx`
```tsx filename="patterns/auth/store-with-auth.tsx"
const schema = {} as LiveStoreSchema
const storeId = 'demo-store'
const user = { jwt: 'user-token' }
const adapter = makeInMemoryAdapter()
// ---cut---
const useAppStore = () =>
useStore({
storeId,
schema,
adapter,
batchUpdates,
syncPayload: {
authToken: user.jwt, // Using a JWT
},
})
export const App = () => {
const [storeRegistry] = useState(() => new StoreRegistry())
return (
{/* Your app content */}
}
```
On the sync server, validate the token and allow or reject the sync based on the result. See the following example:
## `patterns/auth/pass-auth-payload.ts`
```ts filename="patterns/auth/pass-auth-payload.ts"
const JWT_SECRET = 'a-string-secret-at-least-256-bits-long'
export class SyncBackendDO extends makeDurableObject({
onPush: async (message) => {
console.log('onPush', message.batch)
},
onPull: async (message) => {
console.log('onPull', message)
},
}) {}
export default makeWorker({
syncBackendBinding: 'SYNC_BACKEND_DO',
validatePayload: async (payload: any, context) => {
const { storeId } = context
const { authToken } = payload
if (!authToken) {
throw new Error('No auth token provided')
}
const user = await getUserFromToken(authToken)
if (!user) {
throw new Error('Invalid auth token')
} else {
// User is authenticated!
console.log('Sync backend payload', JSON.stringify(user, null, 2))
}
// Check if token is expired
if (payload.exp && payload.exp < Date.now() / 1000) {
throw new Error('Token expired')
}
await checkUserAccess(user, storeId)
},
enableCORS: true,
})
async function getUserFromToken(token: string): PromiseLoading users...
)
.onSuccess((users) => (
-
{users.map((user) => (
- {user.name} ))}
Error: {error.message}
)
.render()
}
```
### Integrating Effect services
Combine Effect services with LiveStore operations using the store's runtime:
## `patterns/effect/store-setup/services.tsx`
```tsx filename="patterns/effect/store-setup/services.tsx"
// Example service definition
export class MyService extends Context.Tag('MyService')<
MyService,
{
processItem: (name: string) => Effect.Effect<{
name: string
metadata: RecordAdd Todo
updateNewTodoText(e.target.value)} onKeyDown={(e) => { if (e.key === 'Enter') { createTodo() } }} />
```d2
...@../../../../src/content/base.d2
direction: right
Client: {
label: "LiveStore Client"
shape: rectangle
}
CF: {
label: "Cloudflare"
style.stroke-dash: 3
Worker: {
label: "Worker"
shape: rectangle
}
DO: {
label: "Durable Object\n(per storeId)"
shape: rectangle
}
Storage: {
label: "DO SQLite (default)\nor D1 (optional)"
shape: cylinder
}
Worker -> DO: "Route by\nstoreId"
DO -> Storage: "Read/Write"
}
Client -> CF.Worker: "WebSocket / HTTP\npush & pull"
```
Key responsibilities:
- **Worker**: Routes sync requests to Durable Objects by `storeId`, handles auth validation
- **Durable Object**: Manages sync state, handles push/pull operations, maintains WebSocket connections
- **Storage**: Persists events in DO SQLite (default) or D1 (optional)
## Installation
```bash
pnpm add @livestore/sync-cf
```
## Transport modes
The sync provider supports three transport protocols, each optimized for different use cases:
### WebSocket transport (Recommended)
Real-time bidirectional communication with automatic reconnection and live pull support.
## `reference/syncing/cloudflare/client-ws.ts`
```ts filename="reference/syncing/cloudflare/client-ws.ts"
export const syncBackend = makeWsSync({
url: 'wss://sync.example.com',
})
```
### HTTP transport
HTTP-based sync with polling for live updates. Requires the `enable_request_signal` compatibility flag.
## `reference/syncing/cloudflare/client-http.ts`
```ts filename="reference/syncing/cloudflare/client-http.ts"
export const syncBackend = makeHttpSync({
url: 'https://sync.example.com',
livePull: {
pollInterval: 3000, // Poll every 3 seconds
},
})
```
### Durable Object RPC transport
Direct RPC communication between Durable Objects (internal use by `@livestore/adapter-cloudflare`).
## `reference/syncing/cloudflare/client-do-rpc.ts`
```ts filename="reference/syncing/cloudflare/client-do-rpc.ts"
declare const state: CfTypes.DurableObjectState
declare const syncBackendDurableObject: CfTypes.DurableObjectStub'/api/electric'] end subgraph "Infrastructure" ES[Electric Server
':30000'] PG[(Postgres DB)] end LS -->|"GET (pull)"| AP LS -->|"POST (push)"| AP AP -->|"Pull requests
(proxied)"| ES AP -->|"Push events
(direct write)"| PG ES -->|"Listen"| PG style LS fill:#e1f5fe style AP fill:#fff3e0 style ES fill:#f3e5f5 style PG fill:#e8f5e9 ``` The API proxy has dual responsibilities: - **Push Events**: Writes events directly to Postgres tables (bypasses Electric) - **Pull Requests**: Proxies to Electric server for reading events - **Authentication**: Implements your custom auth logic - **Database Management**: Initializes tables and manages connections ## Client setup Basic usage in your worker/server code: ## `reference/syncing/sync-provider/electricsql/client-setup.ts` ```ts filename="reference/syncing/sync-provider/electricsql/client-setup.ts" const _backend = makeSyncBackend({ endpoint: '/api/electric', // Your API proxy endpoint ping: { enabled: true }, }) ``` ## API proxy implementation ElectricSQL requires an API proxy on your server to handle authentication and database operations. Your proxy needs two endpoints: ### Minimal implementation example ## `reference/syncing/sync-provider/electricsql/api-proxy.ts` ```ts filename="reference/syncing/sync-provider/electricsql/api-proxy.ts" const electricHost = 'http://localhost:30000' // Your Electric server /** Placeholder for your database factory function */ declare const makeDb: (storeId: string) => { migrate: () => Promise
'/api/s2'] end subgraph "S2 Cloud" S2[S2 Backend
'*.s2.dev'] end LS -->|"GET (pull)
POST (push)
HEAD (ping)"| AP AP -->|"Authenticated
Requests"| S2 style LS fill:#e1f5fe style AP fill:#fff3e0 style S2 fill:#f3e5f5 ``` The API proxy handles: - **Business logic**: Any kind of business logic that is specific to your application (e.g. rate limiting, auth, logging, etc.) - **S2 Stream Management**: Creates basins and streams as needed - **S2 Request Translation**: Converts LiveStore sync operations to authenticated S2 API calls ## Client setup Basic usage in your worker/server code: ## `reference/syncing/s2/client-setup.ts` ```ts filename="reference/syncing/s2/client-setup.ts" const _backend = makeSyncBackend({ endpoint: '/api/s2', // Your API proxy endpoint // more options... }) ``` ## API proxy implementation S2 requires authentication and stream management that can't be handled directly from the browser. You'll need to implement an API proxy on your server that: 1. **Handles authentication** with S2 using your access token 2. **Manages basins and streams** (creates them if they don't exist) 3. **Proxies requests** between LiveStore and S2 Your proxy needs three endpoints: ### Using helper functions The `@livestore/sync-s2` package provides helper functions to simplify the proxy implementation: ## `reference/syncing/s2/api-proxy-implementation.ts` ```ts filename="reference/syncing/s2/api-proxy-implementation.ts" // Configure S2 connection const s2Config: S2Helpers.S2Config = { basin: process.env.S2_BASIN ?? 'your-basin', token: process.env.S2_ACCESS_TOKEN!, // Your S2 access token } // HEAD /api/s2 - Health check/ping export async function HEAD() { return new Response(null, { status: 200 }) } // GET /api/s2 - Pull events export async function GET(request: Request) { const url = new URL(request.url) const args = S2.decodePullArgsFromSearchParams(url.searchParams) const streamName = S2.makeS2StreamName(args.storeId) // Ensure basin and stream exist await S2Helpers.ensureBasin(s2Config) await S2Helpers.ensureStream(s2Config, streamName) // Build request with appropriate headers and URL // Note: buildPullRequest handles cursor+1 conversion internally const { url: pullUrl, headers } = S2Helpers.buildPullRequest({ config: s2Config, args }) const res = await fetch(pullUrl, { headers }) // For live pulls (SSE), proxy the response if (args.live === true) { if (!res.ok) { return S2Helpers.sseKeepAliveResponse() } return new Response(res.body, { status: 200, headers: { 'content-type': 'text/event-stream' }, }) } // For regular pulls if (!res.ok) { return S2Helpers.emptyBatchResponse() } const batch = await res.text() return new Response(batch, { headers: { 'content-type': 'application/json' }, }) } // POST /api/s2 - Push events export async function POST(request: Request) { const requestBody = await request.json() const parsed = Schema.decodeUnknownSync(S2.ApiSchema.PushPayload)(requestBody) const streamName = S2.makeS2StreamName(parsed.storeId) // Ensure basin and stream exist await S2Helpers.ensureBasin(s2Config) await S2Helpers.ensureStream(s2Config, streamName) // Build push request with proper formatting const pushRequests = S2Helpers.buildPushRequests({ config: s2Config, storeId: parsed.storeId, batch: parsed.batch, }) for (const pushRequest of pushRequests) { const res = await fetch(pushRequest.url, { method: 'POST', headers: pushRequest.headers, body: pushRequest.body, }) if (!res.ok) { return S2Helpers.errorResponse('Push failed', 500) } } return S2Helpers.successResponse() } ``` ### Cursor semantics The S2 sync provider uses a cursor that represents the **last processed record**: - The cursor points to the last S2 sequence number we've seen - S2's `seq_num` parameter expects where to start reading from (inclusive) - The helper functions automatically handle the `+1` conversion: `seq_num = cursor + 1` - When starting from the beginning, cursor is `'from-start'` which maps to `seq_num = 0` ### Important considerations - **Stream provisioning**: The helper functions provide `ensureBasin()` and `ensureStream()` to handle creation automatically. - **Error handling**: The helpers include fallback responses (`emptyBatchResponse()`, `sseKeepAliveResponse()`) to maintain stream continuity during errors. - **Authentication**: Store your S2 access token securely (e.g., environment variables). - **Rate limiting**: Consider implementing rate limiting to protect your S2 quota. - **Response helpers**: Use the provided response helpers (`successResponse()`, `errorResponse()`) for consistent API responses. ## Live pull (SSE) S2 provider supports live pulls over Server-Sent Events (SSE). When `live: true` is passed to `pull`, the client: - Immediately emits one page (possibly empty) with `pageInfo: NoMore`. - Parses SSE frames robustly (multi-line `data:` support) and reacts to typed events: - `event: batch` → parses `data` as S2 `ReadBatch` and emits items. - `event: ping` → ignored; keeps the stream alive. - `event: error` → mapped to `InvalidPullError`. ## Implementation notes ### Data storage & encoding LiveStore leverages S2 streams for durable event storage. Understanding the mapping between LiveStore concepts and S2 primitives helps developers comprehend the persistence layer, though direct manipulation is discouraged. #### LiveStore → S2 mapping **Store to Stream**: Each LiveStore `storeId` maps to exactly one S2 stream. The stream name is derived from the `storeId` after sanitization to meet S2 naming requirements. **Event Encoding**: LiveStore events (`AnyEncodedGlobal`) are JSON-serialized and stored as the `body` field of S2 records. Each event contains: - `name`: Event type identifier - `args`: Event-specific payload data - `seqNum`: LiveStore's global event sequence number - `parentSeqNum`: Previous event's sequence number for ordering - `clientId`: Origin client identifier - `sessionId`: Session that created the event **Record Structure**: When pushed to S2, each LiveStore event becomes one S2 record: #### Sequence number handling **LiveStore and S2 maintain completely independent sequence numbering systems**: - **LiveStore's `seqNum`**: Stored inside the JSON event payload (starts at 0). Used for logical event ordering and cursor management within LiveStore. - **S2's `seq_num`**: Assigned by S2 to each record in the stream (also starts at 0). Used solely for stream positioning when reading records. These are **two separate numbering systems** that happen to both start at 0. While they often align numerically (first event is LiveStore seqNum 0, stored in S2 record with seq_num 0), this is coincidental rather than a direct mapping. The sync provider: - Preserves LiveStore's sequence numbers unchanged in the event payload - Uses S2's seq_num only for querying records from the stream (e.g., "read from position X") - Never relies on S2's seq_num for LiveStore's logical event ordering #### Technical details **Format**: The provider uses `s2-format: raw` when communicating with S2, treating record bodies as UTF-8 JSON strings. **Headers**: S2 record headers are not utilized; all LiveStore metadata is contained within the JSON body. **Batch Operations**: Multiple events can be pushed in a single batch, with each event becoming a separate S2 record while maintaining order. #### Important note **Direct stream manipulation is strongly discouraged**. Always interact with S2 streams through LiveStore's sync provider to ensure: - Proper event encoding/decoding - Sequence number integrity - Cursor management consistency - Compatibility with LiveStore's sync protocol Bypassing LiveStore to modify S2 streams directly may corrupt the event log and break synchronization. # [1. Set up starter project with React, Vite & Tailwind](https://dev.docs.livestore.dev/tutorial/1-setup-starter-project/) ## Set up a starter project with React, Vite & Tailwind We have prepared a [starter project](https://github.com/livestorejs/livestore/tree/dev/examples/tutorial-starter) for you that you can use as a starting point for the tutorial. Download it via the following command:
Expand to view the expected command output
Here's the expected output: ``` ➜ livestore-todo-app git:(main) ✗ pnpm run deploy > livestore-todo-app@0.0.0 deploy /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app > pnpm run build && wrangler deploy > livestore-todo-app@0.0.0 build /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app > tsc -b && vite build vite v7.1.12 building for production... ✓ 29 modules transformed. dist/.assetsignore 0.02 kB dist/index.html 0.47 kB │ gzip: 0.30 kB dist/wrangler.json 1.15 kB │ gzip: 0.56 kB dist/assets/index-DEkdisv2.css 9.64 kB │ gzip: 2.74 kB dist/assets/index-COIOT0yp.js 196.04 kB │ gzip: 61.45 kB ✓ built in 319ms ⛅️ wrangler 4.45.1 ─────────────────── Using redirected Wrangler configuration. - Configuration being used: "dist/wrangler.json" - Original user's configuration: "wrangler.toml" - Deploy configuration file: ".wrangler/deploy/config.json" 🌀 Building list of assets... ✨ Read 7 files from the assets directory /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app/dist 🌀 Starting asset upload... 🌀 Found 4 new or modified static assets to upload. Proceeding with upload... + /index.html + /assets/index-COIOT0yp.js + /livestore.svg + /assets/index-DEkdisv2.css Uploaded 1 of 4 assets Uploaded 2 of 4 assets Uploaded 4 of 4 assets ✨ Success! Uploaded 4 files (2.67 sec) Total Upload: 0.34 KiB / gzip: 0.23 KiB Uploaded livestore-todo-app (13.40 sec) Deployed livestore-todo-app triggers (4.40 sec) https://livestore-todo-app.nikolas-burk.workers.dev Current Version ID: 37ce16a4-0bfd-4ecb-829e-a2737c84d9cf ```Expand to view details about the packages
Here's an overview of each of these dependencies: - `@livestore/livestore@0.4.0-dev.14` → Implements the core LiveStore functionality (schema, events, queries, ...). - `@livestore/wa-sqlite@0.4.0-dev.14` → Implements usage of a [SQLite build in WebAssembly](https://github.com/livestorejs/wa-sqlite), so you can use SQLite inside your browser. - `@livestore/adapter-web@0.4.0-dev.14` → Implements the [LiveStore web adapter.](/platform-adapters/web-adapter) - `@livestore/react@0.4.0-dev.14` → Provides [LiveStore integration for React](https://github.com/livestorejs/wa-sqlite). - `@livestore/peer-deps@0.4.0-dev.14` → Required to [satisfy LiveStore peer dependencies](https://dev.docs.livestore.dev/misc/package-management/#peer-dependencies).Todo List
setInput(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Enter a todo..."
className="flex-1 px-4 py-2 text-sm border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
/>
{todos.map(todo => (
{todos.length === 0 && (
{todo.text}
))}
No todos yet. Add one above!
)}Expand to learn about browser isolation/sessions
**Regular browser tab/windows** - All regular (i.e. "not incognito") tabs/windows share the same browser session. - The LiveStore shared web worker is shared across all these tabs/windows. - OPFS storage is shared across the origin. - ✅ Real-time sync works because they're all using the same LiveStore shared web worker and storage. **Incognito windows** - Incognito mode creates a separate session from regular browsing. - However, multiple incognito tabs/windows opened in the same incognito session still share: - The same LiveStore shared web worker instance. - The same OPFS storage (within that incognito session). - Each incognito session gets isolated storage, but windows within that session are _not_ isolated from each other. Think of it this way: - Regular tabs/windows = Session A (all tabs/windows share the same data). - Incognito tabs/windows = Session B (all incognito tabs/windows share the same data). **To get true isolation** If you want completely isolated instances, you'd need to use: - **Different browser profiles** - Chrome profiles are truly isolated. - **Different browsers** - Chrome vs Firefox vs Safari. - **Different devices** (only possible with the deployed app) - Your computer vs your phone.Expand to view the expected output
``` ✗ pnpm run deploy > livestore-todo-app@0.0.0 deploy /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app > pnpm run build && wrangler deploy > livestore-todo-app@0.0.0 build /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app > tsc -b && vite build vite v7.1.12 building SSR bundle for production... ✓ 1085 modules transformed. dist/livestore_todo_app/.vite/manifest.json 0.16 kB dist/livestore_todo_app/wrangler.json 1.37 kB dist/livestore_todo_app/index.js 1,021.14 kB ✓ built in 1.31s vite v7.1.12 building for production... ✓ 1119 modules transformed. dist/client/index.html 0.47 kB │ gzip: 0.30 kB dist/client/assets/make-shared-worker-CbM93UVL.js 363.01 kB dist/client/assets/livestore.worker-DbNV_so_.js 594.87 kB dist/client/assets/wa-sqlite-CLgeTS2u.wasm 618.93 kB │ gzip: 303.78 kB dist/client/assets/index-DNxhg8nM.css 11.76 kB │ gzip: 3.12 kB dist/client/assets/index-BhsI_Uw7.js 760.04 kB │ gzip: 238.67 kB (!) Some chunks are larger than 500 kB after minification. Consider: - Using dynamic import() to code-split the application - Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks - Adjust chunk size limit for this warning via build.chunkSizeWarningLimit. ✓ built in 4.29s ⛅️ wrangler 4.45.1 ─────────────────── Using redirected Wrangler configuration. - Configuration being used: "dist/livestore_todo_app/wrangler.json" - Original user's configuration: "wrangler.toml" - Deploy configuration file: ".wrangler/deploy/config.json" 🌀 Building list of assets... ✨ Read 8 files from the assets directory /Users/nikolasburk/Projects/LiveStore/plain-react-tutorial/livestore-todo-app/dist/client 🌀 Starting asset upload... 🌀 Found 4 new or modified static assets to upload. Proceeding with upload... + /index.html + /assets/index-BhsI_Uw7.js + /assets/index-DNxhg8nM.css + /assets/livestore.worker-DbNV_so_.js Uploaded 1 of 4 assets Uploaded 2 of 4 assets Uploaded 4 of 4 assets ✨ Success! Uploaded 4 files (3 already uploaded) (4.31 sec) Total Upload: 997.21 KiB / gzip: 208.73 KiB Worker Startup Time: 47 ms Your Worker has access to the following bindings: Binding Resource env.SYNC_BACKEND_DO (SyncBackendDO) Durable Object Uploaded livestore-todo-app (17.72 sec) Deployed livestore-todo-app triggers (9.82 sec) https://livestore-todo-app.nikolas-burk.workers.dev Current Version ID: 8860dd68-6082-4da9-9407-dea670cd8b23 ```Todo List
setInput(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Enter a todo..."
className="flex-1 px-4 py-2 text-sm border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
/>
{todos.map(todo => (
+
{todos.length === 0 && (
+
))}
+ toggleTodo(todo.id, todo.completed)}
+ className="w-4 h-4 cursor-pointer"
+ />
+
+ {todo.text}
+
+
+
+ No todos yet. Add one above!
)}Todo List
setInput(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Enter a todo..."
className="flex-1 px-4 py-2 text-sm border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
/>
+
+ {(['All', 'Active', 'Completed'] as const).map((tab) => (
+
+ ))}
+
{todos.map(todo => (
))}
{todos.length === 0 && (
toggleTodo(todo.id, todo.completed)}
className="w-4 h-4 cursor-pointer"
/>
{todo.text}
No todos yet. Add one above!
)}Todo List
updatedInput(e.target.value)}
onKeyDown={handleKeyDown}
placeholder="Enter a todo..."
className="flex-1 px-4 py-2 text-sm border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
/>
{(['All', 'Active', 'Completed'] as const).map((tab) => (
))}
{todos.map(todo => (
))}
{todos.length === 0 && (
toggleTodo(todo.id, todo.completed)}
className="w-4 h-4 cursor-pointer"
/>
{todo.text}
No todos yet. Add one above!
)}Workspace not found
const addTodo = (text: string) => {
workspaceStore.commit(
workspaceEvents.todoAdded({
todoId: `todo-${Date.now()}`,
text,
}),
)
}
return (
{workspace.name}
Created by: {workspace.createdByUsername}
Store ID: {workspaceStore.storeId}
Todos ({todos.length})
-
{todos.map((todo) => (
- {todo.text} {todo.completed ? '✓' : ''} ))}
My Workspaces
{workspaces.length === 0 ? (No workspaces yet
) : ( workspaces.map((w) => (