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

package/docs/llms.txt

@@ -1,147 +0,0 @@
-# LiveStore Documentation for LLMs
-
-> LiveStore is a client-centric local-first data layer for high-performance apps based on SQLite and event-sourcing.
-
-## Notes
-
-- Most LiveStore APIs are synchronous and don't need `await`
-
-
-## Getting started
-
-- [Getting started with LiveStore + React](/getting-started/react-web): How to use LiveStore with React on the web.
-- [Expo](/getting-started/expo): Learn how to use LiveStore with Expo.
-- [Node](/getting-started/node): Learn how to use LiveStore with Node.
-- [Getting started with LiveStore + Vue](/getting-started/vue): How to use LiveStore with Vue.
-- [Solid](/getting-started/solid): Learn how to use LiveStore with Solid.
-
-## Tutorial
-
-- [Overview and prerequisites](/tutorial/0-welcome)
-- [1. Set up starter project with React, Vite & Tailwind](/tutorial/1-setup-starter-project)
-- [2. Deploy to Cloudflare Workers](/tutorial/2-deploy-to-cloudflare)
-- [3. Read and write todos via LiveStore](/tutorial/3-read-and-write-todos-via-livestore)
-- [4. Sync data to Cloudflare](/tutorial/4-sync-data-via-cloudflare)
-- [5. Expand business logic with more events](/tutorial/5-expand-business-logic)
-- [6. Persist UI state](/tutorial/6-persist-ui-state)
-- [Next steps](/tutorial/7-next-steps)
-
-## Overview
-
-- [Introduction](/overview/introduction)
-- [Why LiveStore?](/overview/why-livestore)
-- [How LiveStore works](/overview/how-livestore-works)
-- [Concepts](/overview/concepts): Concepts in LiveStore
-- [When to use LiveStore (and when not)](/overview/when-livestore): Considerations when deciding to use LiveStore.
-- [Technology comparison](/overview/technology-comparison): How LiveStore compares to other related technologies
-
-## Building with LiveStore
-
-- [Rules for AI agents](/building-with-livestore/rules-for-ai-agents)
-- [Events](/building-with-livestore/events)
-- [Data modeling](/building-with-livestore/data-modeling)
-- [CRUD](/building-with-livestore/crud): CRUD
-- [Store](/building-with-livestore/store)
-- [Complex UI state](/building-with-livestore/complex-ui-state): How to model complex UI state in LiveStore.
-- [Reactivity system](/building-with-livestore/reactivity-system)
-- [Syncing](/building-with-livestore/syncing): Syncing
-- [Debugging a LiveStore app](/building-with-livestore/debugging)
-- [Devtools](/building-with-livestore/devtools)
-- [OpenTelemetry](/building-with-livestore/opentelemetry)
-- [Production checklist](/building-with-livestore/production-checklist): Checklist for productionizing a LiveStore app
-
-### State
-
-- [SQLite state schema](/building-with-livestore/state/sqlite-schema)
-- [SQLite state schema (Effect schema)](/building-with-livestore/state/sqlite-schema-effect)
-- [SQL queries](/building-with-livestore/state/sql-queries)
-- [Materializers](/building-with-livestore/state/materializers)
-- [SQLite in LiveStore](/building-with-livestore/state/sqlite): Notes on how to use SQLite in LiveStore
-
-### Tools
-
-- [LiveStore CLI](/building-with-livestore/tools/cli): Command-line interface for LiveStore project scaffolding and development tools.
-- [MCP integration](/building-with-livestore/tools/mcp): Model Context Protocol integration for AI assistants like Claude.
-
-### Examples
-
-- [Data modeling](/building-with-livestore/examples): How to model data in LiveStore.
-- [Todo app with shared workspaces](/building-with-livestore/examples/todo-workspaces): How to model a todo workspace app with shared workspaces in LiveStore.
-- [Turn-based game](/building-with-livestore/examples/turnbased-game): How to model a turn-based game in LiveStore.
-- [AI agent](/building-with-livestore/examples/ai-agent): How to model an AI agent in LiveStore.
-
-## Framework integrations
-
-- [React integration for LiveStore](/framework-integrations/react-integration): How to integrate LiveStore with React.
-- [Custom elements](/framework-integrations/custom-elements): How to integrate LiveStore with Custom Elements aka Web Components.
-- [Svelte integration](/framework-integrations/svelte-integration): How to integrate LiveStore with Svelte.
-- [Vue integration for LiveStore](/framework-integrations/vue-integration): How to integrate LiveStore with Vue.
-- [Solid integration](/framework-integrations/solid-integration): How to integrate LiveStore with Solid.
-
-## Platform adapters
-
-- [Web adapter](/platform-adapters/web-adapter): Information about LiveStore's web adapter
-- [Expo Adapter](/platform-adapters/expo-adapter): LiveStore adapter for React Native apps built with Expo
-- [Node adapter](/platform-adapters/node-adapter)
-- [Cloudflare Durable Object adapter](/platform-adapters/cloudflare-durable-object-adapter)
-- [Tauri adapter](/platform-adapters/tauri-adapter)
-- [Electron adapter](/platform-adapters/electron-adapter)
-
-## Sync providers
-
-- [Cloudflare Workers](/sync-providers/cloudflare)
-- [ElectricSQL](/sync-providers/electricsql)
-- [S2](/sync-providers/s2): Use the official S2 backend with LiveStore via @livestore/sync-s2
-- [Build your own sync provider](/sync-providers/custom)
-
-## Patterns
-
-- [Server-side clients](/patterns/server-side-clients)
-- [Encryption](/patterns/encryption)
-- [Effect](/patterns/effect)
-- [Rich Text Editing](/patterns/rich-text-editing)
-- [Auth](/patterns/auth)
-- [Rich text editing](/patterns/rich-text-editing)
-- [List Ordering](/patterns/list-ordering): Implement drag-and-drop list ordering with fractional indexing
-- [External data](/patterns/external-data)
-- [Offline support](/patterns/offline)
-- [Side effect](/patterns/side-effects): How to run side-effects for LiveStore events
-- [Version control](/patterns/version-control)
-- [Anonymous user transition](/patterns/anonymous-user-transition): How to transition an anonymous user to a logged in user
-- [File management](/patterns/file-management): How to manage files with LiveStore
-- [State machines](/patterns/state-machines): How to use state machines with LiveStore
-- [App evolution](/patterns/app-evolution): How to evolve your app and roll out new app versions
-- [Storybook testing (React)](/patterns/storybook): How to set up LiveStore with Storybook for component development and testing in React.
-- [Undo/Redo](/patterns/undo-redo): How to implement undo/redo functionality with LiveStore
-- [File structure](/patterns/file-structure)
-- [Presence](/patterns/presence): How to implement presence functionality with LiveStore
-- [ORM](/patterns/orm): How to use an ORM with LiveStore
-- [AI](/patterns/ai): How to use LiveStore to build AI applications
-
-## Understanding LiveStore
-
-- [Event sourcing](/understanding-livestore/event-sourcing): Why and how LiveStore uses event sourcing for data flow, syncing and migrations.
-- [Design decisions](/understanding-livestore/design-decisions): Design decisions and trade-offs made in the development of LiveStore
-
-## Sustainable open source
-
-- [Sponsoring LiveStore](/sustainable-open-source/sponsoring)
-
-### Contributing
-
-- [Info](/sustainable-open-source/contributing/info): Notes for developers interested in contributing to LiveStore.
-- [Monorepo](/sustainable-open-source/contributing/monorepo): Notes on the monorepo setup of LiveStore.
-- [Docs](/sustainable-open-source/contributing/docs): Notes on contributing to the LiveStore docs
-
-## Miscellaneous
-
-- [Frequently asked questions](/misc/FAQ): Frequently asked questions about LiveStore
-- [State of the project](/misc/state-of-the-project): A high-level overview of the current state of the project.
-- [Performance](/misc/performance)
-- [Community](/misc/community)
-- [Troubleshooting](/misc/troubleshooting): Common issues in apps using LiveStore and possible solutions.
-- [Credits](/misc/credits): Credits and acknowledgements
-- [Resources](/misc/resources): Resources, assets, logos, etc about LiveStore
-- [Design partners](/misc/design-partners)
-- [Code of conduct](/misc/CODE_OF_CONDUCT): Our code of conduct for the LiveStore community.
-- [Note on package management](/misc/package-management)

package/docs/misc/CODE_OF_CONDUCT/index.md

@@ -1,133 +0,0 @@
-# Code of conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[contact@livestore.dev][Contact].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][Homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][Translations].
-
-[Homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[Translations]: https://www.contributor-covenant.org/translations
-[Contact]: mailto:contact@livestore.dev

package/docs/misc/FAQ/index.md

@@ -1,37 +0,0 @@
-# Frequently asked questions
-
-### Does LiveStore have optimistic updates?
-
-Yes and no. LiveStore doesn't have the concept of optimistic updates as you might know from libraries like [React Query](https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates), however, any data update in LiveStore is automatically optimistic without the developer having to implement any special logic.
-
-This provides the benefits of optimistic updates without the extra complexity by manually having to implement the logic for each individual data update (which can be very error prone).
-
-### Does LiveStore have database transactions?
-
-LiveStore runs on the client-side and handles transactions differently than traditional server-side databases. While materializers automatically run in transactions, global transactional behavior (often called "online transactions") needs to be explicitly modeled in your application logic.
-
-### Can I use an ORM or query builder with LiveStore?
-
-It's possible to use most ORMs/query builders with LiveStore (as long as they are able to synchronously generate SQL statements). You should also give the built-in LiveStore query builder a try. See [the ORM page](/patterns/orm) for more information.
-
-### Is there a company behind LiveStore? How does LiveStore make money?
-
-LiveStore is developed by [Johannes Schickling](https://github.com/schickling) and has been incubated as the foundation of [Overtone](https://overtone.pro) (a local-first music app). The plan is to keep the development of LiveStore as sustainable as possible via sponsorships and other paths (e.g. commercial licenses, paid consulting, premium devtools, etc).
-
-### Is there a hosted sync backend provided by LiveStore?
-
-No, LiveStore is designed to be self-hosted or be used with a 3rd party sync backend.
-
-### Can I use my existing database with LiveStore? {#existing-database}
-
-Not currently. LiveStore is built around the idea of event-sourcing which separates reads and writes. This means LiveStore isn't syncing your database directly but only the events that are used to materialize the database making sure it's kept in sync across clients.
-
-However, we might provide support for this in the future depending on demand.
-
-### What's the difference between clientId, sessionId, and userId?
-
-- **sessionId**: Identifies a single LiveStore instance within a client (e.g., a browser tab). Sessions can persist (e.g., across tab reloads in web).
-- **clientId**: A randomly generated identifier managed by LiveStore that identifies a client instance. Each client has its own unique clientId and can have one or multiple sessions.
-- **userId**: Not a LiveStore concept. User identity must be handled at the application level through your events and application logic.
-
-A single user might have multiple clients (e.g., using different browsers or devices), each with its own clientId. User identification should be modeled within your application domain.

package/docs/misc/community/index.md

@@ -1,88 +0,0 @@
-# Community
-
-## Discord
-
-You can join the Discord server <a href={DISCORD_INVITE_URL}>here</a>.
-
-## Office hours
-
-You can join future office hour events [here](https://lu.ma/livestore).
-
-{
-  officeHours.map((url) => (
-    <iframe
-      width="560"
-      height="315"
-      src={url}
-      title="YouTube video player"
-      frameborder="0"
-      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-      allowfullscreen
-      style={{ aspectRatio: '16 / 9' }}
-    />
-  ))
-}
-
-## Conference talks & podcasts
-
-- [Native-Grade Web Apps with Local-First Data (ViteConf 2025)](https://www.youtube.com/watch?v=h5Bs0vEka5U)
-- [Sync different: Event sourcing in local-first apps](https://www.youtube.com/watch?v=nyPl84BopKc)
-- [From Prisma Founder to LiveStore: Building local-first apps with Johannes Schickling (Aaron Francis interview)](https://www.youtube.com/watch?v=aKTbGIrkrLE)
-
-## RFX: Request for exploration \{#rfx\}
-
-LiveStore opens the door to many new possibilities. Many more than I could explore or build myself, so I invite you to explore some of the ideas below.
-
-### Technological ideas
-
-- Auth
-  - Authn
-  - Authz
-  - e2ee
-- Server side
-  - React server rendering
-  - Centralized read models
-- Integrating with existing databases / systems
-- CRDTs for text editing
-  - Automerge / YJS as embedded data
-- Collaboration
-  - Presence features
-  - Blob files
-- Version control
-  - Manual push/pull + git-like commits of multiple events
-- Event-sourcing
-  - Schema evolution: migrating events (e.g. cambria)
-- Cross-app data interop
-- AI
-  - Local RAG
-  - Agents
-
-### Application ideas
-
-It would be great to see a new generation of apps built with LiveStore - ideally each app being:
-
-- [Local-first](https://www.inkandswitch.com/essay/local-first/)
-- Open-source
-- Self-hostable
-
-Here are some app ideas:
-
-- Replacement for Doodle
-- Replacement for Canny (feature requests)
-- Replacement for Splitwise
-- Replacement for Wunderlist
-- GitHub client
-- A secret Santa app
-- Movie / TV tracking app
-- Fitness app
-
-### LiveStore internals
-
-- Explore and improve multi-store ergonomics
-- Diff queries in SQLite
-- IVM
-
-## Notable LiveStore projects (open-source)
-
-- [WorkSquared](https://github.com/sociotechnica-org/work-squared): An AI-haunted workplace to coordinate, plan, and execute.
-- [Cheffect](https://github.com/tim-smart/cheffect): Local-first recipe management app built with LiveStore and Effect

package/docs/misc/credits/index.md

@@ -1,14 +0,0 @@
-# Credits
-
-LiveStore wouldn't have been possible without the help and support of many individuals and companies.
-
-A special thanks goes to:
-
-- Geoffrey Litt & Nicholas Schiefer for the collaboration of the [Riffle research project](https://riffle.systems/essays/prelude/) on which LiveStore is based on
-- Matt Wonlaw for the collaboration on LiveStore over an extended period of time
-- [Kuldar](https://kuldar.com) for the lovely LiveStore logo
-- Ink & Switch for their visionary [local-first research](https://inkandswitch.com/local-first/) and for being a continuous source of inspiration
-- The SQLite team for their amazing work on the SQLite core library
-- Roy Hashimoto for their great work on the SQLite WASM library [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) which LiveStore uses a fork of
-- Tim Suchanek for the initial collaboration on the Effect DB schema library
-- All sponsors, users & community members for feedback and support

package/docs/misc/design-partners/index.md

@@ -1,13 +0,0 @@
-# Design partners
-
-LiveStore is looking for design partners with the following aims:
-- For your company:
-  - Architectural guidance and internal training
-  - Priority support
-  - Influence over the roadmap and prioritization of features/bugfixes
-  - Make sure LiveStore is well-maintained as a critical part of your product
-- For LiveStore:
-  - Sustain the continous development and maintenance of the project
-  - Make sure LiveStore is a designed around real-world use cases and constraints
-
-Please [get in touch](https://forms.gle/NUy9irooEpXjqFAb6) if you're interested in becoming a design partner.

package/docs/misc/package-management/index.md

@@ -1,21 +0,0 @@
-# Note on package management
-
-export const catalog = `\
-catalog:
-  effect: ${EFFECT_VERSION} # As LiveStore depends on \`effect\`
-	# also \`react\`, \`react-dom\` etc based on your project
-`
-
-## Recommended
-
-It's strongly recommended to use `pnpm` or `bun` when building an app with LiveStore to avoid dependency issues (e.g. wrong version resolution, duplicate dependencies, etc).
-
-### Peer dependencies
-
-Since LiveStore has a few peer dependencies, you either should manually add them to your project or add the `@livestore/peer-deps` package to your project to satisfy them.
-
-### PNPM Catalog
-
-When using `pnpm`, we recommend specifying the following packages in your [PNPM Catalog](https://pnpm.io/catalogs):
-
-<Code code={catalog} lang="yaml" title="pnpm-workspace.yaml" />

package/docs/misc/performance/index.md

@@ -1,25 +0,0 @@
-# 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)

package/docs/misc/resources/index.md

@@ -1,46 +0,0 @@
-# Resources
-
-Feel free to use the following assets for presentations, blog posts, etc about LiveStore.
-
-## Logo
-
-<table>
-  <thead>
-    <tr>
-      <th style="text-align: center;">Dark PNG</th>
-      <th style="text-align: center;">Dark SVG</th>
-      <th style="text-align: center;">Light PNG</th>
-      <th style="text-align: center;">Light SVG</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td style="background-color: #333333; padding: 30px; text-align: center;">
-        <img src="/resources/logo-dark.png" width="200" alt="LiveStore Logo Dark PNG" />
-      </td>
-      <td style="background-color: #333333; padding: 30px; text-align: center;">
-        <img src="/resources/logo-dark.svg" width="200" alt="LiveStore Logo Dark SVG" />
-      </td>
-      <td style="background-color: #F0F0F0; padding: 30px; text-align: center;">
-        <img src="/resources/logo-light.png" width="200" alt="LiveStore Logo Light PNG" />
-      </td>
-      <td style="background-color: #F0F0F0; padding: 30px; text-align: center;">
-        <img src="/resources/logo-light.svg" width="200" alt="LiveStore Logo Light SVG" />
-      </td>
-    </tr>
-  </tbody>
-</table>
-
-## Architecture diagrams
-
-### Client scenarios
-
-<iframe src='https://www.tldraw.com/p/NJKH2PHghAeJC-7UIC1xF?d=v-97.-1297.3177.3303.ZMsCZoB-D6VX-W2poI5Gm' style={{ height: '400px', width: '100%' }} />
-
-### Sync architecture
-
-<iframe src='https://www.tldraw.com/p/CWLjWxk0On_rAtjsJ4vt2?d=v-491.-533.2303.2394.RaypXEQgx30bxQnCcVFAG' style={{ height: '400px', width: '100%' }} />
-
-### Data modeling
-
-<iframe src='https://www.tldraw.com/p/7yByV0g6ksHmbIORnwoH3?d=v-336.-500.1614.1677.RnlHGrijaybsLhyM0sTlL' style={{ height: '400px', width: '100%' }} />

package/docs/misc/state-of-the-project/index.md

@@ -1,37 +0,0 @@
-# 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)

package/docs/misc/troubleshooting/index.md

@@ -1,82 +0,0 @@
-# Troubleshooting
-
-### Store / sync backend is stuck in a weird state
-
-While hopefully rare in practice, it might still happen that a client or a sync backend is stuck in a weird/invalid state. Please report such cases as a [GitHub issue](https://github.com/livestorejs/livestore/issues).
-
-To avoid being stuck, you can either:
-
-- use a different `storeId`
-- or reset the sync backend and local client for the given `storeId` 
-
-## React related issues
-
-### Rebase loop triggers repeated event emissions
-
-Symptoms
-- Logs repeatedly show messages like: `merge:pull:rebase: rollback` and the same local events being rolled back and replayed.
-
-Why this happens
-- LiveStore uses optimistic local commits and rebasing during sync. On pull, the client rolls back local events, applies the remote head, then replays local events — and only then refreshes reactive queries (transactional from the UI’s perspective).
-- If your app emits events from a reactive effect based on read‑model changes (e.g., “when the latest item changes, emit X”), the effect runs after each completed rebase. Without a rebase‑safe guard, it can emit the same logical event repeatedly across rebases.
-- Multiple windows/devices for the same user can also emit the same logical event at nearly the same time. Even if writes are idempotent, the extra local commits still cause additional rebases and effect re‑runs.
-
-Circuit breaker fix (rebase‑safe)
-- Implement a session‑local circuit breaker: track which logical actions you’ve already emitted in this session using an in‑memory set. This guard is not affected by rollback/replay, so it prevents re‑emitting across rebases.
-- Avoid feedback loops: don’t use the same store state you’re writing as the primary trigger.
-
-Example pattern (React)
-
-```tsx
-// Pseudocode – rebase‑safe circuit breaker for side‑effects
-const circuitBreakerRef = useRef<Set<string>>(new Set())
-const latest = useLatestItemFromStore() // derived read‑model state
-
-React.useEffect(() => {
-  if (!latest) return
-
-  const key = latest.logicalId
-  if (circuitBreakerRef.current.has(key)) return // session‑local guard (not rolled back)
-
-  circuitBreakerRef.current.add(key) // open the breaker before emitting
-  store.commit(events.someEvent({ id: deterministicIdFrom(latest), ... }))
-}, [latest, store])
-```
-
-Checklist
-- Use a deterministic id for the event when possible.
-- Gate emission with a session‑local circuit breaker to avoid re‑emitting across rebases.
-- Keep effect dependencies minimal; avoid depending on store state that you also update in the same effect.
-
-Note on terminology
-- “Circuit breaker” here refers to an app‑level guard that prevents repeated side‑effect emissions across rebases. It is distinct from the traditional network/service circuit‑breaker pattern (failure threshold/open/half‑open) but serves a similar purpose of preventing repeated work under specific conditions.
-
-### Query doesn't update properly
-
-If you notice the result of a `useQuery` hook is not updating properly, you might be missing some dependencies in the query's hash.
-
-For example, the following query:
-
-```ts
-// Don't do this
-const query$ = useQuery(queryDb(tables.issues.query.where({ id: issueId }).first()))
-//                                                              ^^^^^^^ missing in deps
-
-// Do this instead
-const query$ = useQuery(queryDb(tables.issues.query.where({ id: issueId }).first(), { deps: [issueId] }))
-```
-
-## `node_modules` related issues
-
-### `Cannot execute an Effect versioned ...`
-
-If you're seeing an error like `RuntimeException: Cannot execute an Effect versioned 3.10.13 with a Runtime of version 3.10.12`, you likely have multiple versions of `effect` installed in your project.
-
-As a first step you can try deleting `node_modules` and running `pnpm install` again.
-
-If the issue persists, you can try to add `"resolutions": { "effect": "3.15.2" }` or [`pnpm.overrides`](https://pnpm.io/package_json#pnpmoverrides) to your `package.json` to force the correct version of `effect` to be used.
-
-## Package management
-
-- Please make sure you only have a single version of any given package in your project (incl. LiveStore and other packages like `react`, etc). Having multiple versions of the same package can lead to all kinds of issues and should be avoided. This is particularly important when using LiveStore in a monorepo.
-- Setting `resolutions` in your root `package.json` or tools like [PNPM catalogs](https://pnpm.io/catalogs) or [Syncpack](https://github.com/JamieMason/syncpack) can help you manage this.