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

package/docs/misc/CODE_OF_CONDUCT/index.md

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

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

@@ -0,0 +1,87 @@
+# 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
+
+- [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

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

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

@@ -0,0 +1,21 @@
+# 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/resources/index.md

@@ -0,0 +1,46 @@
+# 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/sponsoring/index.md

@@ -0,0 +1,104 @@
+# Sponsoring LiveStore
+
+## TLDR
+
+- Sponsoring LiveStore helps ensure long-term stability and improvements for the project you rely on.
+- Sponsors receive exclusive benefits, including a LiveStore Devtools license and access to sponsor-only resources.
+- LiveStore is fully open source and community-supported—your sponsorship directly enables its ongoing development.
+
+<Sponsor />
+
+## Goal: Sustainable Open Source
+
+As the creator and maintainer of LiveStore, I'm often asked *"how do you make money with LiveStore?"*. That's a great question with a simple answer. I'm not building LiveStore to make a lot of money - my goal is to make LiveStore a sustainable open source project. I've been working on LiveStore since 2021 (mostly full-time) and hope you can help to keep the project sustainable.
+
+Open source has been a big part of my life - I've founded [Prisma](https://www.prisma.io/), created [Contentlayer](https://www.contentlayer.dev/), and built/maintained many other open source projects over the years. Through these experiences, I've seen firsthand how challenging it can be to keep open source projects healthy in the long run. Too often, maintainers burn out, and projects that many people depend on end up dying. My goal with LiveStore is to build an open source project that's sustainable and could possibly serve as an inspiration for other open source projects.
+
+I wanted LiveStore to exist for over a decade - something I felt was missing in the ecosystem and that I know others have wanted as well. But building and maintaining a project on that level of ambition is incredibly hard, especially without a clear path to monetization. I believe that's also why a technology like LiveStore didn't exist yet. 
+
+Particularly being concerned about the sustainability of open source projects, I was hesitant to start another open source project myself. Still, I believe deeply in the value LiveStore creates for developers, and I'm committed to making it the best it can be.
+
+The unfortunate reality is that there is no well-established way for open source creators to get paid for their work. While there are some great initiatives and platforms out there - like [Open Source Pledge](https://opensourcepledge.org/), [Generous](https://generous.builders/), [GitHub Sponsors](https://github.com/sponsors), [Polar](https://polar.sh/), [OpenCollective](https://opencollective.com/), and [thanks.dev](https://thanks.dev/) - most open source projects still struggle to capture even a fraction of the value they create. I believe in a positive-sum world, and I'm happy to contribute, but sustainability is essential if LiveStore is going to keep growing and improving.
+
+My mid-/long term goal is to bring in enough resources not just to support myself, but to pay others to work on LiveStore as well. I want to ensure that the project remains stable, well-maintained, and innovative - something you can truly rely on. Sponsorship is the most direct way to make this possible. It's not just about funding features or bug fixes; it's about creating a relationship where your support helps guarantee the future of a tool you depend on.
+
+I hope those words resonate with you and you'll understand why sponsoring LiveStore isn't just a nice gesture - it's essential for keeping the project going and a direct investment in the stability and evolution of a project that your application (and business) depends on. Your support ensures that LiveStore remains sustainable and healthy for the whole community.
+
+Thank you! 🧡
+
+## Related posts
+
+- [The Open Source Sustainability Crisis](https://openpath.quest/2024/the-open-source-sustainability-crisis/) by Chad Whitacre
+- [Entitlement in Open Source](https://mikemcquaid.com/entitlement-in-open-source/) by Homebrew lead Mike McQuaid
+
+## Aligned Incentives
+
+-	**Stability and Reliability:**
+  Your application depends on LiveStore as the core data foundation. Sponsorship ensures continuous, focused maintenance and improvement, directly benefiting you with increased stability, reliability, and performance.
+
+-	**Shared Investment in Long-term Success:**
+  Sponsorship creates mutual investment in the project's future. You sponsoring LiveStore signals that it is crucial to your business, motivating me (and other maintainers) to prioritize features, enhancements, and fixes that benefit you.
+
+-	**Avoiding Costly In-House Development:**
+  LiveStore offers a unique architectural design with (currently) no direct alternatives readily available. So the only alternative is building something similar in-house which is takes a lot of time and resources. Sponsorship aligns incentives by ensuring LiveStore remains an attractive and efficient alternative.
+
+-	**Transparent Sustainability:**
+  Open-source sustainability is a common challenge as projects stagnate without sustainable resources. Sponsorship transparently addresses this, providing maintainers with clarity and stability, ensuring the project thrives and evolves to users' benefit.
+
+-	**Healthy Community and Ecosystem**:
+  Sponsors actively contribute to fostering a healthy, collaborative ecosystem. Their direct involvement ensures responsiveness to real-world needs, creating an ongoing, beneficial dialogue between users and maintainers.
+
+-	**Focused Innovation and Quality**:
+  Regular sponsorship allows maintainers to allocate dedicated time to innovative research and high-quality development. This ultimately translates into more reliable software, fewer bugs, faster releases, and thoughtful features driven by actual user needs.
+
+-	**Ensuring Longevity and Avoiding Lock-In**:
+  By aligning financial incentives through sponsorship, maintainers avoid being forced into less favorable monetization methods (e.g., restrictive licensing or heavy commercial lock-ins), maintaining open access and flexibility for users.
+
+## Sponsor Benefits
+
+You can access your sponsor benefits via the [Sponsor dashboard](https://livestore.dev/sponsor).
+
+- [LiveStore Devtools](/reference/devtools) License
+- Access to
+  - Sponsor-only Discord channels
+  - LiveStore Office Hours
+- Prioritized bug fixes and feature requests
+
+## Thanks to our Sponsors
+
+A big and heartfelt thank you to all our sponsors. Your support has been invaluable and LiveStore wouldn't be where it is without you.
+
+### Partners
+
+- [ElectricSQL](https://www.electricsql.com/)
+- [Netlify](https://www.netlify.com/)
+- [Expo](https://expo.dev/)
+- [Axial](https://axial.work/)
+
+### Individuals
+
+A big thank you to all individual GitHub sponsors! 🧡
+
+## FAQ
+
+### Why not raise VC money for LiveStore?
+
+While raising venture capital for LiveStore might be possible, the challenge lies in building a VC-scale business around LiveStore. My current goal is to make and keep LiveStore sustainable without investor funding. (While I don't rule out this path in the future, it's currently not planned.)
+
+### Why not build a hosting service around LiveStore?
+
+While technically feasible, LiveStore embraces partnerships with other syncing services to create a win-win situation and minimize vendor lock-in for users.
+
+### Are free devtools licenses for students?
+
+Yes, please reach out via Discord.
+
+### Are there other ways to support LiveStore?
+
+Yes, there are many ways to support LiveStore:
+
+- Become a [contributor / maintainer](/contributing/contributing)
+- Help other community members (e.g. via Discord)
+- Spread the word
+  - Give talks, write blog posts, post on social media, ...
+- Provide feedback (e.g. via GitHub issues or Discord)

package/docs/misc/troubleshooting/index.md

@@ -0,0 +1,82 @@
+# 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.

package/docs/patterns/ai/index.md

@@ -0,0 +1,15 @@
+# AI
+
+- LiveStore is a great fit for building AI applications.
+- Scenarios:
+  - Local RAG (via sqlite-vec (see [feature request](https://github.com/livestorejs/livestore/issues/127)) + local LLM e.g. Gemini Nano embedded in Chrome)
+  - Agentic applications
+
+- Event <> tool calls
+  - Nice mapping
+
+## Example
+
+```ts
+// TODO (contribution welcome)
+```

package/docs/patterns/anonymous-user-transition/index.md

@@ -0,0 +1,10 @@
+# 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.

package/docs/patterns/app-evolution/index.md

@@ -0,0 +1,72 @@
+# App Evolution
+
+When building an app with LiveStore, you'll need to keep some things in mind when evolving your app.
+
+## Schema changes
+
+### State schema changes
+
+Generally any kind of changes to your state schema (e.g. SQLite tables, ...) can be done at any time without any further considerations assuming the event materializer is updated to support the new schema.
+
+### Event schema changes
+
+Event schema changes require a bit more consideration. Changes to the event schema should generally be done in a backwards-compatible way. See [Event schema evolution](/reference/events/#schema-evolution) for more details.
+
+## Parallel different app versions
+
+In scenarios where you have multiple app versions rolled out in parallel (e.g. app version v3 with event schema v3 and app version v4 with event schema v4), you'll need to keep the following in mind:
+
+App instances running version 4 might commit events that are not yet supported by version 3. Your app needs to decide how to handle this scenario in one of the following ways:
+
+- Ignore unknown events
+- Cause an error in the app for unknown events
+- Handle events with a "catch all" event handler
+- Let app render a "app update required" screen. App can still be used in read-only mode.
+- ...
+
+LiveStore exposes a dedicated `unknownEventHandling` configuration on `makeSchema` so you can codify the desired behaviour instead of sprinkling ad-hoc checks across your app. The default is `'warn'`, which logs every unknown event and keeps processing.
+
+## `reference/events/unknown-event-handling.ts`
+
+```ts filename="reference/events/unknown-event-handling.ts"
+
+const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text(),
+    },
+  }),
+} 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 }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+// ---cut---
+
+const _schema = makeSchema({
+  events,
+  state,
+  unknownEventHandling: {
+    strategy: 'callback',
+    onUnknownEvent: (event, error) => {
+      console.warn('LiveStore saw an unknown event', { event, reason: error.reason })
+    },
+  },
+})
+```
+
+Set the strategy to `'ignore'` to silently skip forward-only events, `'fail'` to stop immediately (useful during development), or `'callback'` to forward them to custom telemetry while continuing to replay the log.