This is the full developer documentation for LiveStore. ## Notes - Most LiveStore APIs are synchronous and don't need `await` # Start of LiveStore documentation # [Docs](https://dev.docs.livestore.dev//) ## State of the documentation Please note that the documentation is still work in progress with many parts missing and often only containing notes/bullet points. ### Docs for LLMs We support the [llms.txt](https://llmstxt.org/) convention for making documentation available to large language models and the applications that make use of them. Currently, we have the following root-level files: ### NPM packages - Main package: - Framework integrations: - React: - Solid: - Platform adapters: - Web: - Expo: - Node: - Sync provider: - Cloudflare: - Electric: - Devtools: - Vite: - Expo: - SQLite packages: - sqlite-wasm (wrapper around wa-sqlite): - wa-sqlite fork: - Internal packages: - - - # [Docs](https://dev.docs.livestore.dev/contributing/docs/) Please follow LiveStore's [guiding principles](/contributing/contributing#guiding-principles) when writing docs. ## Writing style This project broadly tries to follow the [Prisma docs style guide](https://www.prisma.io/docs/about/style-guide/writing-style). ## Snippets For snippet guidelines, see: `/contributor-docs/docs/snippets.md` ## Deploying the docs - Run `direnv exec . mono docs deploy` to build and deploy the documentation to the dev domain (`https://dev.docs.livestore.dev`). - Passing `--prod` targets the production domain (`https://docs.livestore.dev`) when you are on `main` (otherwise the command deploys using a branch alias). - Use `--site=` if you need to override the default Netlify site name. - Add `--purge-cdn` when you need to invalidate Netlify's CDN cache after deploying; this ensures new edge handlers or content-negotiation changes take effect immediately. - CI automatically builds and deploys the docs: `main` updates `https://docs.livestore.dev`, `dev` updates `https://dev.docs.livestore.dev`, and feature branches publish to the dev domain behind a branch alias. # [Contributing](https://dev.docs.livestore.dev/contributing/contributing/) ## Before contributing First of all, thank you for your interest in contributing to LiveStore! Building LiveStore has been an incredible amount of work, so everyone interested in contributing is very much appreciated. 🧡 Please note that LiveStore is still in active development with many things yet subject to change (e.g. APIs, examples, docs, etc). Before you start contributing, please check with the maintainers if the changes you'd like to make are likely to be accepted. Please get in touch via the `#contrib` channel on [Discord](https://discord.gg/RbMcjUAPd7). ## Areas for contribution There are many ways to contribute to LiveStore. ### Help wanted for ... - You can look at ["help wanted" issues](https://github.com/livestorejs/livestore/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) on GitHub for ideas. - [SQLite WASM build](https://github.com/livestorejs/wa-sqlite) maintainer (e.g. keeping it up to date with upstream SQLite and wa-sqlite versions) - Examples maintainer (e.g. keeping dependencies & best practices up to date) - Solid integration maintainer (e.g. keeping it up to date with upstream Solid versions) ### In scope and encouraged - Documentation improvements - Improving examples - Test cases - Bug fixes - Benchmarking ### Potentially in scope - New features - Larger architectural changes in the core library - Adding new examples - Adding new integrations (e.g. for technologies such as Svelte, Vue, ...) - Monorepo setup changes - Changes to the docs site/setup ### Out of scope (for now) - Changes to the landing page - Changes to the devtools - Rewriting the core library in a different language ### Open research questions - Safer event schema evolution - Incremental view maintenance for complex SQLite database views Please get in touch if you'd like to discuss any of these topics! ## Bug reports - Please include a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) for how to reproduce the bug. ## Guiding principles {#guiding-principles} - Keep it as simple as possible - Reduce surface area - Make the right thing easy - Document the "why" # [Monorepo](https://dev.docs.livestore.dev/contributing/monorepo/) ## Prerequisites ### Personal experience Depending on the kind of contribution you're interested in, the following experience is recommended: - Deep experience with TypeScript (incl. type-level programming) - Experience with TypeScript monorepo setups - Experience with distributed systems - Experience with [Effect](https://effect.website) (or willingness to learn) ### Recommended tooling: Use devenv + direnv for a consistent setup To make development easy and consistent across systems and platforms, this project uses [Nix](https://zero-to-nix.com/) with [devenv](https://devenv.sh) to manage "system dependencies" such as Node.js, Bun, etc. Use [direnv](https://direnv.net) (recommended) to automatically load the environment, or run commands explicitly with devenv, for example: `devenv shell pnpm install`. ### Manual setup You'll need to have a recent version the following tools installed: - Node.js - Bun - pnpm ## Initial setup ```bash git clone git@github.com:livestorejs/livestore.git cd livestore # Loads env vars, installs deps and builds the project ./bootstrap.sh ``` ## General notes - TypeScript - LiveStore tries to follow the strictest TypeScript rules possible to ensure type safety and avoid subtle bugs. - LiveStore also makes heavy use of [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html). - Package management - This project uses [pnpm](https://pnpm.io/) to manage the workspace. - LiveStore is primarily developed in VSCode/Cursor. - Testing - LiveStore uses Vitest for most tests and Playwright for browser tests. ### Notable used tools / technologies - [TypeScript](https://www.typescriptlang.org/) - [Effect](https://effect.website) - [pnpm](https://pnpm.io/) - [Bun](https://bun.sh/) - [Vitest](https://vitest.dev/) - [Playwright](https://playwright.dev/) - [OpenTelemetry](https://opentelemetry.io/) - [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (included as git subtree) - see [wa-sqlite management](../../../../contributor-docs/wa-sqlite-management.md) - [Nix](https://zero-to-nix.com/) - [Direnv](https://direnv.net/) - [devenv](https://devenv.sh) ### Environment variables The `.envrc` file contains all necessary environment variables for the project. You can create a `.envrc.local` file to override or add variables for your local setup. You'll need to run `direnv allow` to load the environment variables. ### VSCode tasks - This project is primarily developed in VSCode and makes use of [tasks](https://code.visualstudio.com/docs/editor/tasks) to run commands. - Common tasks are: - `dev:ts:watch` to run the TypeScript compiler in watch mode for the entire monorepo - `pnpm:install` to install all dependencies (e.g. when changing a `package.json`) ## Tasks to run before committing Please run the following tasks before committing & pushing: - `mono ts` to build the TypeScript code - `mono lint` to run the linting checks - `mono test` to run the tests ## Examples - Once you've set up the monorepo locally, you'll find all examples in the `/examples` directory. - All examples are self-contained and can be run independently. - Examples use explicit version dependencies (e.g., `0.3.2-dev.0`) for LiveStore packages. - Examples are not part of the monorepo TypeScript build system to maintain independence. - Each example has its own TypeScript configuration that's independent of the monorepo build system. #### Making changes to examples 1. Make your desired changes directly in `/examples/`. 2. Test your changes by running the example (e.g., `pnpm dev` in the example directory). 3. Commit your changes. ### OpenTelemetry setup As a local OpenTelemetry setup, we recommend the [docker-otel-lgtm](https://github.com/grafana/docker-otel-lgtm) setup. Add the following to your `.envrc.local` file: ```bash export VITE_GRAFANA_ENDPOINT="http://localhost:30003" export GRAFANA_ENDPOINT="http://localhost:30003" export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" export VITE_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" ``` ### TypeScript - Each package has its own `tsconfig.json` file which extends the root `tsconfig.base.json`. - This project makes heavy use of TypeScript project references. ### Package management - This project uses [pnpm](https://pnpm.io/) to manage the workspace. - We're using the `workspace:*` protocol to link packages together. - We should try to keep dependencies to an absolute minimum and only add them if we absolutely need them. - We also need to manually add peer dependencies for each package. - We should try to avoid duplicate dependencies across the monorepo as much as possible as duplicate dependencies can lead to a lot of issues and pain. - We're also using the `resolutions` field in the root `package.json` to force some packages to be the same across the monorepo (ideally not needed but for some packages it's necessary currently). - We're using [syncpack](https://github.com/JamieMason/syncpack) to help maintain consistent dependency versions across the monorepo. - See `syncpack.config.mjs` for the configuration. - Common commands: - `bunx syncpack format` to format the `package.json` files - `bunx syncpack lint` to check all version ranges - `bunx syncpack fix-mismatches` to adjust versions across `package.json` files (check before with `lint`) - `bunx syncpack update` to update packages across the monorepo to the latest versions ### Notes on external dependencies LiveStore tries to use as few external dependencies as possible. Given LiveStore is built on top of Effect, which can be considered a standard library for TypeScript, it should handle most use cases. #### Notes on some packages The following packages need to be updated with extra care: - `react`/`react-dom` as we need to move in lockstep with Expo / React Native (currently pinned to {REACT_VERSION}) - `effect` (currently pinned to {EFFECT_VERSION}) #### Effect - LiveStore makes heavy use of the [Effect](https://effect.website) library and ecosystem throughout the implementation of the various packages. - Effect is not imposed on the app developers using LiveStore but where it makes sense, LiveStore is also exposing a Effect-based API (e.g. `createStore`). #### Updating dependencies - Either update the versions manually in each `package.json` file or use `bunx syncpack update`. ### Notes on monorepo structure - The `@livestore/utils` package re-exports many common modules/functions (e.g. from `effect`) in order to - Reduce the number of direct dependencies for other packages - Allows for convenient extension of modules (e.g. adding methods to `Effect.___`, `Schema.___`, ...) ## Docs The LiveStore docs are built with [Astro Starlight](https://starlight.astro.build/). ## Related external repos - [Fork of wa-sqlite](https://github.com/livestorejs/wa-sqlite) with Nix build setup included as git subtree. - The source code of the devtools is currently not part of this monorepo but in a separate private repo. # [AI agent](https://dev.docs.livestore.dev/data-modeling/ai-agent/) LiveStore is a great fit for building AI agents. TODO: actually write this section # [Complex UI state](https://dev.docs.livestore.dev/data-modeling/complex-ui-state/) LiveStore is a great fit for building apps with complex UI state. TODO: actually write this section # [Data Modeling](https://dev.docs.livestore.dev/data-modeling//) ## Core idea - Data modeling is probably the most important part of any app and needs to be done carefully. - The core idea is to model the read and write model separately. - Depending on the use case, you might also want to split up the read/write model into separate "containers" (e.g. for data-sharing/scalability/access control reasons). - There is no transactional consistency between containers. - Caveat: Event sourcing is not ideal for all use cases - some apps might be better off with another approach (e.g. use CRDTs for rich text editing). ## Considerations for data modeling - How much data do you expect to have and what is the shape of the data? - Some kind of data needs special handling (e.g. blobs or rich text) - Access patterns (performance, ...) - Access control - Data integrity / consistency - Sharing / collaboration - Regulatory requirements (e.g. GDPR, audit logs, ...) ## TODO - TODO: actually write this section - questions to answer - When to split things into separate containers? - How do migrations work? - Read model migrations - Write model migrations - How to create new write models based on existing ones - Example: An app has multiple workspaces and you now want to introduce the concept of "projects" inside a workspace. You might want to pre-populate a "default workspace project" for each workspace. # [Todo app with shared workspaces](https://dev.docs.livestore.dev/data-modeling/todo-workspaces/) Let's consider a fairly common application scenario: An app (in this case a todo app) with shared workspaces. For the sake of this guide, we'll keep things simple but you should be able to nicely extend this to a more complex app. ## Requirements - There are multiple independent todo workspaces - Each workspace is initially created by a single user - Users can join the workspace by knowing the workspace id and get read and write access - For simplicity, the user identity is chosen when the app initially starts (i.e. a username) but in a real app this would be handled by a proper auth setup ## Data model - We are splitting up our data model into two kinds of stores (with respective eventlogs and SQLite databases): The `workspace` store and the `user` store. ### `workspace` store (one per workspace) For the `workspace` store we have the following events: - `workspaceCreated` - `todoAdded` - `todoCompleted` - `todoDeleted` - `userJoined` And the following state model: - `workspace` table (with a single row for the workspace itself) - `todo` table (with one row per todo item) - `member` table (with one row per user who has joined the workspace) ### `user` store (one per user) For the `user` store we have the following events: - `workspaceCreated` - `workspaceJoined` And the following state model: - `user` table (with a single row for the user itself) Note that the `workspaceCreated` event is used both in the `workspace` and the `user` store. This is because each eventlog should be "self-sufficient" and not rely on other eventlogs to be present to fulfill its purpose. ## Schemas **User store:** ## `data-modeling/todo-workspaces/multi-store/user.schema.ts` ```ts filename="data-modeling/todo-workspaces/multi-store/user.schema.ts" // Emitted when this user creates a new workspace const workspaceCreated = Events.synced({ name: 'v1.WorkspaceCreated', schema: Schema.Struct({ workspaceId: Schema.String }), }) // Emitted when this user joins an existing workspace const workspaceJoined = Events.synced({ name: 'v1.WorkspaceJoined', schema: Schema.Struct({ workspaceId: Schema.String }), }) const events = { workspaceCreated, workspaceJoined } // Table to store basic user info // Contains only one row as this store is per-user. const userTable = State.SQLite.table({ name: 'user', columns: { // Assuming username is unique and used as the identifier username: State.SQLite.text({ primaryKey: true }), }, }) // Table to track which workspaces this user is part of const userWorkspaceTable = State.SQLite.table({ name: 'userWorkspace', columns: { workspaceId: State.SQLite.text({ primaryKey: true }), // Could add role/permissions here later }, }) export const userTables = { user: userTable, userWorkspace: userWorkspaceTable } const materializers = State.SQLite.materializers(events, { // When the user creates or joins a workspace, add it to their workspace table 'v1.WorkspaceCreated': ({ workspaceId }) => userTables.userWorkspace.insert({ workspaceId }), 'v1.WorkspaceJoined': ({ workspaceId }) => userTables.userWorkspace.insert({ workspaceId }), }) const state = State.SQLite.makeState({ tables: userTables, materializers }) export const schema = makeSchema({ events, state }) ``` **Workspace store:** ## `data-modeling/todo-workspaces/multi-store/workspace.schema.ts` ```ts filename="data-modeling/todo-workspaces/multi-store/workspace.schema.ts" // Emitted when a new workspace is created (originates this store) const workspaceCreated = Events.synced({ name: 'v1.WorkspaceCreated', schema: Schema.Struct({ workspaceId: Schema.String, name: Schema.String, createdByUsername: Schema.String, }), }) // Emitted when a todo item is added to this workspace const todoAdded = Events.synced({ name: 'v1.TodoAdded', schema: Schema.Struct({ todoId: Schema.String, text: Schema.String }), }) // Emitted when a todo item is marked as completed const todoCompleted = Events.synced({ name: 'v1.TodoCompleted', schema: Schema.Struct({ todoId: Schema.String }), }) // Emitted when a todo item is deleted (soft delete) const todoDeleted = Events.synced({ name: 'v1.TodoDeleted', schema: Schema.Struct({ todoId: Schema.String, deletedAt: Schema.Date }), }) // Emitted when a new user joins this workspace const userJoined = Events.synced({ name: 'v1.UserJoined', schema: Schema.Struct({ username: Schema.String }), }) export const workspaceEvents = { workspaceCreated, todoAdded, todoCompleted, todoDeleted, userJoined } // Table for the workspace itself (only one row as this store is per-workspace) const workspaceTable = State.SQLite.table({ name: 'workspace', columns: { workspaceId: State.SQLite.text({ primaryKey: true }), name: State.SQLite.text(), createdByUsername: State.SQLite.text(), }, }) // Table for the todo items in this workspace const todoTable = State.SQLite.table({ name: 'todo', columns: { todoId: State.SQLite.text({ primaryKey: true }), text: State.SQLite.text(), completed: State.SQLite.boolean({ default: false }), // Using soft delete by adding a deletedAt timestamp deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }), }, }) // Table for members of this workspace const memberTable = State.SQLite.table({ name: 'member', columns: { username: State.SQLite.text({ primaryKey: true }), // Could add role/permissions here later }, }) export const workspaceTables = { workspace: workspaceTable, todo: todoTable, member: memberTable } const materializers = State.SQLite.materializers(workspaceEvents, { 'v1.WorkspaceCreated': ({ workspaceId, name, createdByUsername }) => [ workspaceTables.workspace.insert({ workspaceId, name, createdByUsername }), // Add the creator as the first member workspaceTables.member.insert({ username: createdByUsername }), ], 'v1.TodoAdded': ({ todoId, text }) => workspaceTables.todo.insert({ todoId, text }), 'v1.TodoCompleted': ({ todoId }) => workspaceTables.todo.update({ completed: true }).where({ todoId }), 'v1.TodoDeleted': ({ todoId, deletedAt }) => workspaceTables.todo.update({ deletedAt }).where({ todoId }), 'v1.UserJoined': ({ username }) => workspaceTables.member.insert({ username }), }) const state = State.SQLite.makeState({ tables: workspaceTables, materializers }) export const schema = makeSchema({ events: workspaceEvents, state }) ``` ## Using the Multi-Store API Now that we've defined our schemas, let's set up the multi-store API to manage workspace and user stores dynamically. :::caution[Experimental API] This guide uses the [experimental multi-store API](/reference/framework-integrations/react-integration#multi-store) which is still early in its development. If you have feedback or questions about this API, please don't hesitate to comment on the [RFC](https://github.com/livestorejs/livestore/pull/585) ::: ### Store Configuration First, define store options for each store type using [`storeOptions()`](/reference/framework-integrations/react-integration#storeoptionsoptions): **Workspace store:** ## `data-modeling/todo-workspaces/multi-store/workspace.store.ts` ```ts filename="data-modeling/todo-workspaces/multi-store/workspace.store.ts" const adapter = makePersistedAdapter({ storage: { type: 'opfs' }, worker, sharedWorker, }) // Define workspace store configuration // Each workspace gets its own isolated store instance export const workspaceStoreOptions = (workspaceId: string) => storeOptions({ storeId: `workspace:${workspaceId}`, schema, adapter, gcTime: 60_000, // Keep in memory for 60 seconds after last use }) ``` **User store:** ## `data-modeling/todo-workspaces/multi-store/user.store.ts` ```ts filename="data-modeling/todo-workspaces/multi-store/user.store.ts" const adapter = makePersistedAdapter({ storage: { type: 'opfs' }, worker, sharedWorker, }) // Define user store configuration // Each user has their own store to track which workspaces they're part of export const userStoreOptions = (username: string) => storeOptions({ storeId: `user:${username}`, schema, adapter, gcTime: Number.POSITIVE_INFINITY, // Keep user store in memory indefinitely }) ``` ### App Setup Create a [`StoreRegistry`](/reference/framework-integrations/react-integration#new-storeregistryconfig) and provide it to your React app: ## `data-modeling/todo-workspaces/multi-store/App.tsx` ```tsx filename="data-modeling/todo-workspaces/multi-store/App.tsx" export function App({ children }: { children: ReactNode }) { const [storeRegistry] = useState( () => new StoreRegistry({ defaultOptions: { batchUpdates, }, }), ) return {children} } ``` ### Accessing Stores Use the [`useStore()`](/reference/framework-integrations/react-integration#usestoreoptions) hook to access specific workspace instances: ## `data-modeling/todo-workspaces/multi-store/Workspace.tsx` ```tsx filename="data-modeling/todo-workspaces/multi-store/Workspace.tsx" // Component that accesses a specific workspace store function WorkspaceContent({ workspaceId }: { workspaceId: string }) { // Load the workspace store for this specific workspace const workspaceStore = useStore(workspaceStoreOptions(workspaceId)) // Query workspace data const [workspace] = workspaceStore.useQuery(queryDb(workspaceTables.workspace.select().limit(1))) const todos = workspaceStore.useQuery(queryDb(workspaceTables.todo.select())) if (!workspace) return
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 ? '✓' : ''}
    • ))}
) } // Workspace component with Suspense and ErrorBoundary export function Workspace({ workspaceId }: { workspaceId: string }) { return ( Error loading workspace}> Loading workspace...}> ) } ``` ### Loading Multiple Workspaces To display all workspaces for a user, first load the user store to get their workspace list, then dynamically load each workspace: ## `data-modeling/todo-workspaces/multi-store/WorkspaceList.tsx` ```tsx filename="data-modeling/todo-workspaces/multi-store/WorkspaceList.tsx" // Component that displays all workspaces for a user function WorkspaceListContent({ username }: { username: string }) { // Load the user store to get their workspace list const userStore = useStore(userStoreOptions(username)) // Query all workspaces this user belongs to const workspaces = userStore.useQuery(queryDb(userTables.userWorkspace.select())) return (

My Workspaces

{workspaces.length === 0 ? (

No workspaces yet

) : ( workspaces.map((w) => (
)) )}
) } // Full workspace list with Suspense export function WorkspaceList({ username }: { username: string }) { return ( Error loading workspaces}> Loading workspaces...}> ) } ``` ## Further notes To make this app more production-ready, we might want to do the following: - Use a proper auth setup to enforce a trusted user identity - Introduce a proper user invite process - Introduce access levels (e.g. read-only, read-write) - Introduce end-to-end encryption ### Individual todo stores for complex data If each todo item has a lot of data (e.g. think of a GitHub/Linear issue with lots of details), it might make sense to split up each todo item into its own store. This would create **3 store types** instead of 2: - **User stores** (one per user) - unchanged - **Workspace stores** (one per workspace) - only basic todo metadata - **Todo stores** (one per todo item) - rich todo data Your app would then have **N + M + K stores** total (N workspaces + M users + K todo items). This pattern improves performance by only loading detailed todo data when specifically viewing that item, and prevents large todos from slowing down workspace syncing. # [Turn-based game](https://dev.docs.livestore.dev/data-modeling/turnbased-game/) LiveStore is a great fit for turn-based games. In this guide we'll look at a simple turn-based game and how to model it in LiveStore. General idea: Let server enforce the logic that each player only commits one action per turn. TODO: write rest of guide # [Design Decisions](https://dev.docs.livestore.dev/evaluation/design-decisions/) ## Goals - Fast, synchronous, transactional, and reactive state management - Global state is eventually consistent - Persistent storage - Syncing - Convenient schema migrations - Great devtools ## Major Design Decisions - Based on [event-sourcing](/evaluation/event-sourcing) (implying a read/write model separation) - Using SQLite for state management over JavaScript implementations - There are many benefits to using SQLite for state management, including performance, reliability, and ease of use. - Run in-memory SQLite in main-thread to enable synchronous queries - Usually LiveStore is used with a second SQLite database for persistence running in a separate thread (e.g. web worker) - Running SQLite additionally in the main-thread however also means each tab uses extra memory. - The current implementation of LiveStore assumes that the data is small enough to fit in memory. However, SQLite is very efficient so this should work for many use cases and apps. - LiveStore implements a Signals-based reactivity system based on the ideas of Adapton for incremental computation - The goal is to keep LiveStore syncing provider agnostic so you can use the right syncing provider for your use case. ## Implementation decisions - Build most of the library in TypeScript. We might move more parts to Rust in the future. - Embrace and build on top of [Effect](https://effect.website) as a library of powerful primitives, particularly for IO/concurrency heavy parts of the library. ## Original motivation - Frustration with database schema migrations -> event sourcing to separate read and write model (avoid schema migrations for read model) - Applying the "Make the right thing easy" principle to app data management # [How LiveStore works](https://dev.docs.livestore.dev/evaluation/how-livestore-works/) ### TLDR LiveStore uses event sourcing to sync events across clients and materialize state into a local, reactive SQLite database. ## 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 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 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 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 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 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 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 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 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. Two main scenarios can occur during a push attempt: 1. **Client In Sync:** If the client's local eventlog is already up-to-date with the sync backend (i.e., no new remote events have arrived since the last pull/push), the local event is pushed directly. 2. **Concurrent Incoming Events:** If new remote events have been pulled in the background, or are discovered during the push attempt, the client first processes these incoming remote events. Any local, unpushed events are then rebased on top of these new remote events before being pushed to the sync backend. 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 LiveStore includes platform adapters to integrate with various environments, such as web browsers, mobile applications (iOS/Android), desktop applications, and Node.js. # [Event Sourcing](https://dev.docs.livestore.dev/evaluation/event-sourcing/) - Similar to Redux but persisted and synced across devices - Provides a more principled way to handle data instead of relying on mutable state - Core idea: Separate read vs write model - Read model: App database (i.e. SQLite) - Write model: Ordered log of all mutation events - Related topics - Domain driven design - Benefits - Simple mental model - Preserves user intent - Scalable - Flexible - You can easily evolve the read model based on your query patterns as your app requirements change over time - Flexible merge conflicts resolution - Automatic migrations of the read model (i.e. app database) - Write model can also be evolved (e.g. via versioned mutations and optionally mapping old mutations to new ones) - History of all state changes is captured (e.g. for auditing and debugging) - Foundation for syncing - Downsides - Slightly more boilerplate to manually define mutations - Need to be careful so eventlog doesn't grow too much ## LiveStore as an event-sourcing framework While the benefits of event sourcing are compelling, building a robust system from scratch is complex and time-consuming. Developers often encounter pitfalls related to data consistency, schema migrations, and efficient state reconstruction. LiveStore provides an off-the-shelf event sourcing solution designed for ease of use and correctness. It simplifies development by: - Providing clear APIs for defining mutations (events). - Automatically managing the event log persistence and ordering. - Efficiently recomputing the state (e.g. SQLite database) from the eventlog via materializers. - Handling complexities like automatic data migrations and offering strategies for conflict resolution during synchronization. This allows you to leverage the power of event sourcing without needing to implement the underlying infrastructure and tackle common edge cases yourself. ## Further reading - [The Log: What every software engineer should know about real-time data's unifying abstraction](https://engineering.linkedin.com/distributed-systems/log-what-every-software-engineer-should-know-about-real-time-datas-unifying) # [Performance](https://dev.docs.livestore.dev/evaluation/performance/) LiveStore is designed with performance in mind. To ensure consistent speed and minimal resource consumption, we maintain a suite of performance tests that run automatically on every commit to `main` and every pull request. These tests help us detect regressions early and identify performance bottlenecks for implementing optimizations. ## Performance tests Our current test suite focuses on two key metrics: **latency** and **memory usage**. We measure these two metrics across various user interaction scenarios on a minimal LiveStore+React test app. We select scenarios that help stress-test LiveStore’s ability to handle common underlying tasks that are part of common user interactions. To learn more about our testing methodology, check out the [README](https://github.com/livestorejs/livestore/blob/main/tests/perf/README.md) of our performance tests. > **Future expansions:** We [plan](https://github.com/livestorejs/livestore/blob/main/tests/perf/README.md#future-improvements) to measure throughput and bundle size, as well as expand the selection of scenarios and dimensions for the tests. ## Latest test results You can view the latest performance test results on our [public dashboard](https://livestore.grafana.net/public-dashboards/4a9a3b7941464bcebbc0fa2cdddc3130). Otherwise, you can view the latest test results by inspecting the logs of the `perf-test` job in our [GitHub Actions workflow](https://github.com/livestorejs/livestore/actions/workflows/ci.yml). ## Reporting a performance issue We’re committed to transparency and continuous improvement. If you find performance gaps or regressions in your own usage, please [file an issue](https://github.com/livestorejs/livestore/issues/new) # [State of the project](https://dev.docs.livestore.dev/evaluation/state-of-the-project/) LiveStore is based on years of research (see [Riffle](https://riffle.systems/essays/prelude/)) and is used as the foundation for ambitious apps such as [Overtone](https://overtone.pro). LiveStore has been in development since 2021 and is making good progress towards a stable release. LiveStore is not yet ready for all production scenarios. ## Current state LiveStore is currently in **beta** with most APIs being fairly stable (there might still be some breaking changes in coming releases). Most work is currently focussed on reliability and performance improvements. There is currently no specific timeline for a 1.0 release but we are making good progress in that direction. ### On breaking changes While LiveStore is in beta there can be three kinds of breaking changes: - Breaking API changes - Client storage format changes (whenever `liveStoreStorageFormatVersion` is updated) - Sync backend storage format changes (e.g. when a sync backend implementation changes the way how it stores data) We try our best to minimize breaking changes and to provide a migration path whenever possible. ## Roadmap See [GitHub issues](https://github.com/livestorejs/livestore/issues) for more details. Get in touch if you have any questions or feedback. ### 2025 Q3 - Adapter bug fixes & stability improvements - Performance improvements - Syncing latency & throughput - More testing ### Long-term - Eventlog compaction [#136](https://github.com/livestorejs/livestore/issues/136) - Support more syncing providers - Support more framework integrations - Support more platforms (e.g. Electron, Tauri) # [Technology comparison](https://dev.docs.livestore.dev/evaluation/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](/reference/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. 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/evaluation/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](/evaluation/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 ## 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? # [Cloudflare Durable Objects Examples](https://dev.docs.livestore.dev/examples/cloudflare-adapter/) # Cloudflare Durable Objects Examples Examples using `@livestore/adapter-cloudflare` for Cloudflare Workers and Durable Objects. ## Cloudflare Adapter - Runs LiveStore inside Cloudflare Durable Objects - Uses Durable Object Storage API (not traditional databases) - SQLite WASM with Cloudflare-specific VFS - No WebSocket support - uses Durable Objects' distributed consistency --- View all examples on GitHub → # [Expo Adapter Examples](https://dev.docs.livestore.dev/examples/expo-adapter/) # Expo Adapter Examples Examples using `@livestore/adapter-expo` for React Native mobile applications. ## Expo Adapter - Uses native Expo SQLite stored in device's SQLite directory - Requires New Architecture (Fabric) - incompatible with old architecture - Single-threaded operation in main thread - WebSocket connections for sync via React Native dev server --- View all examples on GitHub → # [Examples](https://dev.docs.livestore.dev/examples//) # Example Applications Discover how to build local-first applications with LiveStore through our comprehensive collection of example apps. Each example demonstrates different features, patterns, and platform integrations to help you get started quickly. ## Browse by Platform Adapter LiveStore supports multiple platform adapters, each optimized for different environments. Choose the adapter that matches your target platform: ## Getting Started 1. **Choose your platform** from the adapter categories above 2. **Browse examples** that match your use case and framework preference 3. **Clone and run** the examples locally to see LiveStore in action 4. **Study the source code** to understand patterns and best practices ## Multi-Adapter Examples Some examples demonstrate **cross-platform synchronization** by using multiple adapters: - **CF Chat** uses both Web and Cloudflare adapters for hybrid client-server architecture - **Sync-enabled examples** show how to connect different platforms seamlessly ## About LiveStore LiveStore is a local-first data layer that runs everywhere - from browsers to mobile apps to edge computing. Each adapter provides platform-optimized features while maintaining a consistent API across all environments. --- View all examples on GitHub → # [Node Adapter Examples](https://dev.docs.livestore.dev/examples/node-adapter/) # Node Adapter Examples Examples using `@livestore/adapter-node` for Node.js server-side applications. ## Node Adapter - Uses native Node.js SQLite with file system storage - Stores SQLite files directly on disk (default: current directory) - Supports single-threaded or worker thread modes - WebSocket connections for sync and devtools integration --- View all examples on GitHub → # [Expo](https://dev.docs.livestore.dev/getting-started/expo/) export const CODE = { babelConfig: babelConfigCode, metroConfig: metroConfigCode, } {/* We're adjusting the package to use the dev version on the dev branch */} export const manualInstallDepsStr = [ '@livestore/devtools-expo' + versionNpmSuffix, '@livestore/adapter-expo' + versionNpmSuffix, '@livestore/livestore' + versionNpmSuffix, '@livestore/react' + versionNpmSuffix, '@livestore/sync-cf/client' + versionNpmSuffix, '@livestore/peer-deps' + versionNpmSuffix, 'expo-sqlite', ].join(' ') ### Prerequisites - Recommended: Bun 1.2 or higher - Node.js {MIN_NODE_VERSION} or higher To use [LiveStore](/) with [Expo](https://docs.expo.dev/), ensure your project has the [New Architecture](https://docs.expo.dev/guides/new-architecture/) enabled. This is required for transactional state updates. ### Option A: Quick start For a quick start we recommend using our template app following the steps below. For existing projects see [Existing project setup](#existing-project-setup). 1. **Set up project from template** Replace `livestore-app` with your desired app name. 2. **Install dependencies** It's strongly recommended to use `bun` or `pnpm` for the simplest and most reliable dependency setup (see [note on package management](/misc/package-management) for more details). ```bash bun install ``` ```bash pnpm install --node-linker=hoisted ``` Make sure to use `--node-linker=hoisted` when installing dependencies in your project or add it to your `.npmrc` file. ``` # .npmrc nodeLinker=hoisted ``` Hopefully Expo will also support non-hoisted setups in the future. ```bash npm install ``` When using `yarn`, make sure you're using Yarn 4 or higher with the `node-modules` linker. ```bash yarn set version stable yarn config set nodeLinker node-modules yarn install ``` Pro tip: You can use [direnv](https://direnv.net/) to manage environment variables. 3. **Run the app** In a new terminal, start the Cloudflare Worker (for the sync backend): ### Option B: Existing project setup \{#existing-project-setup\} 1. **Install dependencies** 2. **Add Vite meta plugin to babel config file** LiveStore Devtools uses Vite. This plugin emulates Vite's `import.meta.env` functionality. In your `babel.config.js` file, add the plugin as follows: 3. **Update Metro config** Add the following code to your `metro.config.js` file: ## Define Your Schema Create a file named `schema.ts` inside the `src/livestore` folder. This file defines your LiveStore schema consisting of your app's event definitions (describing how data changes), derived state (i.e. SQLite tables), and materializers (how state is derived from events). Here's an example schema: ## `getting-started/expo/livestore/schema.ts` ```ts filename="getting-started/expo/livestore/schema.ts" 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 }), deletedAt: State.SQLite.integer({ nullable: true, schema: Schema.DateFromNumber }), }, }), uiState: State.SQLite.clientDocument({ name: 'uiState', schema: Schema.Struct({ newTodoText: Schema.String, filter: Schema.Literal('all', 'active', 'completed') }), default: { id: SessionIdSymbol, value: { newTodoText: '', filter: 'all' } }, }), } 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 }), }), todoUncompleted: Events.synced({ name: 'v1.TodoUncompleted', schema: Schema.Struct({ id: Schema.String }), }), todoDeleted: Events.synced({ name: 'v1.TodoDeleted', schema: Schema.Struct({ id: Schema.String, deletedAt: Schema.Date }), }), todoClearedCompleted: Events.synced({ name: 'v1.TodoClearedCompleted', schema: Schema.Struct({ deletedAt: Schema.Date }), }), uiStateSet: tables.uiState.set, } const materializers = State.SQLite.materializers(events, { 'v1.TodoCreated': ({ id, text }) => tables.todos.insert({ id, text, completed: false }), 'v1.TodoCompleted': ({ id }) => tables.todos.update({ completed: true }).where({ id }), 'v1.TodoUncompleted': ({ id }) => tables.todos.update({ completed: false }).where({ id }), 'v1.TodoDeleted': ({ id, deletedAt }) => tables.todos.update({ deletedAt }).where({ id }), 'v1.TodoClearedCompleted': ({ deletedAt }) => tables.todos.update({ deletedAt }).where({ completed: true }), }) const state = State.SQLite.makeState({ tables, materializers }) export const schema = makeSchema({ events, state }) ``` ## Add the LiveStore Provider To make the LiveStore available throughout your app, wrap your app's root component with the `LiveStoreProvider` component from `@livestore/react`. This provider manages your app’s data store, loading, and error states. Here's an example: ## `getting-started/expo/Root.tsx` ```tsx filename="getting-started/expo/Root.tsx" const storeId = 'expo-todomvc' const syncUrl = 'https://example.org/sync' const adapter = makePersistedAdapter({ sync: { backend: makeWsSync({ url: syncUrl }) }, }) export const Root: FC = () => ( Loading LiveStore ({status.stage})...} renderError={(error) => Error: {String(error)}} renderShutdown={() => LiveStore shutdown} boot={(store) => { if (store.query(tables.todos.count()) === 0) { store.commit(events.todoCreated({ id: crypto.randomUUID(), text: 'Make coffee' })) } }} > ) ``` ### `getting-started/expo/components/ListTodos.tsx` ```tsx filename="getting-started/expo/components/ListTodos.tsx" export const ListTodos: FC = () => { const { store } = useStore() const todos = useQuery(visibleTodos$) const toggleTodo = useCallback( ({ id, completed }: typeof tables.todos.Type) => { store.commit(completed ? events.todoUncompleted({ id }) : events.todoCompleted({ id })) }, [store], ) const clearCompleted = () => store.commit(events.todoClearedCompleted({ deletedAt: new Date() })) return ( {todos.map((todo) => ( {todo.text} {todo.completed ? 'Completed' : 'Pending'}