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

package/docs/tutorial/3-read-and-write-todos-via-livestore/index.md

@@ -45,7 +45,7 @@ Here's an overview of each of these dependencies:
 
 - `@livestore/livestore@0.4.0-dev.14` → Implements the core LiveStore functionality (schema, events, queries, ...).
 - `@livestore/wa-sqlite@0.4.0-dev.14` → Implements usage of a [SQLite build in WebAssembly](https://github.com/livestorejs/wa-sqlite), so you can use SQLite inside your browser.
-- `@livestore/adapter-web@0.4.0-dev.14` → Implements the [LiveStore web adapter.](https://dev.docs.livestore.dev/reference/platform-adapters/web-adapter/)
+- `@livestore/adapter-web@0.4.0-dev.14` → Implements the [LiveStore web adapter.](/platform-adapters/web-adapter)
 - `@livestore/react@0.4.0-dev.14` → Provides [LiveStore integration for React](https://github.com/livestorejs/wa-sqlite).
 - `@livestore/peer-deps@0.4.0-dev.14` → Required to [satisfy LiveStore peer dependencies](https://dev.docs.livestore.dev/misc/package-management/#peer-dependencies).
 
@@ -53,7 +53,7 @@ Here's an overview of each of these dependencies:
 
 ## Define your LiveStore schema
 
-In this step, you're going to define the [schema](/reference/state/sqlite-schema/) that LiveStore uses to represent the data of your app. The schema is one of the core concepts of LiveStore.
+In this step, you're going to define the [schema](/building-with-livestore/state/sqlite-schema) that LiveStore uses to represent the data of your app. The schema is one of the core concepts of LiveStore.
 
 Your LiveStore-related files typically live in a `livestore` directory in your app, so create that first:
 
@@ -64,9 +64,9 @@ touch src/livestore/schema.ts
 
 The schema contains three major components:
 
-- The [**table**](/reference/state/sqlite-schema/#defining-tables) structures of your local SQLite database.
+- The [**table**](/building-with-livestore/state/sqlite-schema#defining-tables) structures of your local SQLite database.
 - The [**events**](https://dev.docs.livestore.dev/reference/events/) that can be emitted by your app.
-- The [**materializers**](https://dev.docs.livestore.dev/reference/state/materializers/) that use the events to alter the state of your database.
+- The [**materializers**](/building-with-livestore/state/materializers) that use the events to alter the state of your database.
 
 Here's how you define the schema for the current version of the todo app:
 
@@ -110,7 +110,7 @@ Here's a quick summary of the code:
 The `tables`, `events` and `materializers` are packaged up into a `schema` object that's needed in the parts of your app where you interact with LiveStore.
 
 :::note[Versioning events and materializers]
-You may have noticed that event and materializer names are prefixed with `v1`. 
+You may have noticed that event and materializer names are prefixed with `v1`.
 
 It's good practice in LiveStore to version your events and materializers to ensure future compatibility between them as your app evolves.
 :::
@@ -119,10 +119,11 @@ It's good practice in LiveStore to version your events and materializers to ensu
 
 To now "connect" LiveStore with your React app, you need to:
 
-1. Create the [LiveStore web worker](/reference/platform-adapters/web-adapter/#web-worker) that is responsible for the logic of persisting data on your file system.
-2. Create a LiveStore [adapter](/reference/platform-adapters/web-adapter/) that enables persistences with local SQLite via [OPFS](https://web.dev/articles/origin-private-file-system).
-3. Wrap your root component in `main.tsx` with the LiveStore [provider](https://dev.docs.livestore.dev/reference/framework-integrations/react-integration/#livestoreprovider) (which will receive both the web worker and adapter from above as arguments).
-4. Update your Vite Config to work with LiveStore.
+1. Create the [LiveStore web worker](/platform-adapters/web-adapter#web-worker) that is responsible for the logic of persisting data on your file system.
+2. Create a LiveStore [adapter](/platform-adapters/web-adapter) that enables persistence with local SQLite via [OPFS](https://web.dev/articles/origin-private-file-system).
+3. Create a store configuration file that exports a custom hook wrapping [`useStore()`](/framework-integrations/react-integration#1-configure-the-store).
+4. Create and provide a `StoreRegistry` with [`<StoreRegistryProvider>`](/framework-integrations/react-integration#2-set-up-the-registry) in `main.tsx`.
+5. Update your Vite Config to work with LiveStore.
 
 Let's get started!
 
@@ -145,9 +146,13 @@ This is boilerplate code that you'll almost never need to touch. (In this tutori
 When importing this file, make sure to add the `?worker` extension to the import path to ensure that [Vite treats it as a worker file](https://vite.dev/guide/features.html#web-workers).
 :::
 
-Next, update `main.tsx` to create an adapter and wrap your `App` component inside the `LiveStoreProvider`:
+Next, create a `store.ts` file that defines your store configuration and a `useAppStore()` hook:
 
-```tsx title="src/main.tsx"
+```bash
+touch src/livestore/store.ts
+```
+
+```ts title="src/livestore/store.ts"
 
 const adapter = makePersistedAdapter({
   storage: { type: 'opfs' },
@@ -155,23 +160,37 @@ const adapter = makePersistedAdapter({
   sharedWorker: LiveStoreSharedWorker,
 })
 
-createRoot(document.getElementById('root')!).render(
-  <LiveStoreProvider
-    schema={schema}
-    adapter={adapter}
-    renderLoading={(_) => <div>Loading LiveStore ({_.stage})...</div>}
-    storeId="todo-db-tutorial"
-    batchUpdates={batchUpdates}
-  >
-    <App />
-  </LiveStoreProvider>
-)
+export const useAppStore = () =>
+  useStore({
+    storeId: 'todo-db-tutorial',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+```
+
+Then, update `main.tsx` to wrap your `<App>` component inside the `<StoreRegistryProvider>`:
+
+```tsx title="src/main.tsx"
+
+const Root = () => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
+  return (
+    <Suspense fallback={<div>Loading LiveStore...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <App />
+      </StoreRegistryProvider>
+    </Suspense>
+  )
+}
+
+createRoot(document.getElementById('root')!).render(<Root />)
 ```
 
 :::note[So many "workers" ...]
 There's some ambiguity with the "worker" terminology in this tutorial. In general, there are three different kinds of Workers at play.
 - The **LiveStore web worker** (`LiveStoreWorker`); this is the Worker you defined in `livestore.worker.ts`. Technically, this is a _browser_ web worker, i.e. a separate JavaScript thread that runs in the browser, isolated from the main UI thread.
--  The **LiveStore shared web worker** (`LiveStoreSharedWorker`); you just imported it from `@livestore/adapter-web/shared-worker`, also a _browser_ web worker. It's actually more of an _implementation detail_ but currently required to be exposed, so that the setup works with Vite. 
+-  The **LiveStore shared web worker** (`LiveStoreSharedWorker`); you just imported it from `@livestore/adapter-web/shared-worker`, also a _browser_ web worker. It's actually more of an _implementation detail_ but currently required to be exposed, so that the setup works with Vite.
 - The **Cloudflare Worker** that will automatically sync the data in the background; you'll set this up in the next step.
 
 Note that both the LiveStore web worker and the LiveStore Shared web worker are regular [web workers,](https://www.dhiwise.com/post/web-workers-vs-service-workers-in-javascript#what-are-web-workers-) not [service workers](https://www.dhiwise.com/post/web-workers-vs-service-workers-in-javascript#what-are-service-workers-)!
@@ -181,7 +200,7 @@ Here's how to think about the workers in the context of browser tabs (or windows
 ```
 Tab 1 ──┐
 Tab 2 ──┼──→ Shared Worker (tab coordination) ──→ Web Worker (persistence)
-Tab 3 ──┘ 
+Tab 3 ──┘
 ```
 
 :::
@@ -202,7 +221,7 @@ export default defineConfig({
 })
 ```
 
-Now, your app is set up to start reading and writing data in a local SQLite database via LiveStore. If you run the app via `pnpm dev`, you'll briefly see a loading screen (implemented via the `renderLoading` prop on the `LiveStoreProvider`) before the todo list UI from the previous steps will appear again:
+Now, your app is set up to start reading and writing data in a local SQLite database via LiveStore. If you run the app via `pnpm dev`, you'll briefly see a loading screen (the Suspense fallback) before the todo list UI from the previous steps will appear again:
 
 ![](../../../assets/tutorial/chapter-3/0-livestore-loading.gif)
 
@@ -210,16 +229,16 @@ The todos themselves are not yet persisted because you haven't modified the logi
 
 ## Read and write todos from local SQLite via LiveStore
 
-The current version of the app still stores the todos _in-memory_ via the [state](https://react.dev/learn/state-a-components-memory) of your `App` component. However, with the basic LiveStore setup in place, you can now move to persisting your todos inside SQLite via LiveStore!
+The current version of the app still stores the todos _in-memory_ via the [state](https://react.dev/learn/state-a-components-memory) of your `<App>` component. However, with the basic LiveStore setup in place, you can now move to persisting your todos inside SQLite via LiveStore!
 
-In order to read todos, you need to define a LiveStore [query](/reference/state/sql-queries). LiveStore queries are _live_ or _reactive_, meaning they will automatically update your UI components when the underlying data changes.
+In order to read todos, you need to define a LiveStore [query](/building-with-livestore/state/sql-queries). LiveStore queries are _live_ or _reactive_, meaning they will automatically update your UI components when the underlying data changes.
 
-Here's how you can define and use a query to fetch all todos from the local SQLite database using LiveStore inside the `App` component (you don't need to update your code yet, you'll get the full snippet at the end of this section):
+Here's how you can define and use a query to fetch all todos from the local SQLite database using LiveStore inside the `<App>` component (you don't need to update your code yet, you'll get the full snippet at the end of this section):
 
 ```diff title="src/App.tsx" lang="ts"
 function App() {
 
-+  const { store } = useStore()
++  const store = useAppStore()
 
   // The trailing `$` is a convention to indicate that this
   // variable is a "live query".
@@ -231,7 +250,7 @@ function App() {
 +  const todos = store.useQuery(todos$)
 -  const [todos, setTodos] = useState<Todo[]>([])
 
-  // ... remaining code for the `App` component
+  // ... remaining code for the `<App>` component
 }
 ```
 
@@ -242,13 +261,13 @@ This was only half of the job though: Right now your code would throw a type err
 ```diff title="src/App.tsx" lang="ts"
 function App() {
 
-  const { store } = useStore()
+  const store = useAppStore()
 
   const todos$ = queryDb(() => tables.todos.select())
 
   const todos = store.useQuery(todos$)
 
-  // Commit an event to the `store` instead of 
+  // Commit an event to the `store` instead of
   // updating local React state.
   const addTodo = () => {
 +    store.commit(
@@ -257,7 +276,7 @@ function App() {
     setInput('')
   }
 
-  // Commit an event to the `store` instead of 
+  // Commit an event to the `store` instead of
   // updating local React state.
   const deleteTodo = (id: number) => {
 +    store.commit(
@@ -265,7 +284,7 @@ function App() {
 +    )
   }
 
-  // ... remaining code for the `App` component
+  // ... remaining code for the `<App>` component
 
 }
 ```
@@ -274,13 +293,13 @@ See how the data now will flow through the app _unidirectionally_ with this setu
 
 Let's follow it from the first time the app is started:
 
-1. The `App` component registers the `todos$` "live query" with the store.
+1. The `<App>` component registers the `todos$` "live query" with the store.
 1. The query fires initially; the returned `todos` array is empty.
-1. The `App` component renders an empty list.
+1. The `<App>` component renders an empty list.
 1. A user adds a `todo`; the `todoCreated` event is triggered and committed to the DB.
 1. The `v1.TodoCreated` materializer is invoked and writes the data into the DB.
 1. The `todos$` query fires again because the state of the DB changed; the returned `todos` array now contains the newly created todo.
-1. The `App` component renders a single todo. 
+1. The `<App>` component renders a single todo.
 
 Now try it out! Here's the full code for `App.tsx` that you can copy and paste:
 
@@ -288,7 +307,7 @@ Now try it out! Here's the full code for `App.tsx` that you can copy and paste:
 
 function App() {
 
-  const { store } = useStore()
+  const store = useAppStore()
 
   const todos$ = queryDb(() => tables.todos.select())
   const todos = store.useQuery(todos$)
@@ -435,7 +454,7 @@ Here's a little GIF demonstrating the current state of the live updates via brow
 
 ![](../../../assets/tutorial/chapter-3/3-livestore-sync-local-480.gif)
 
-- When a change is made in one Chrome window, it is automatically reflected in the other Chrome window. 
+- When a change is made in one Chrome window, it is automatically reflected in the other Chrome window.
 - Similarly, when a change is made in one Safari window, it is automatically reflected in the other Safari window.
 
 To recap, here's a visualization of the data flow in the app at this point:
@@ -444,15 +463,15 @@ To recap, here's a visualization of the data flow in the app at this point:
 
 ## Set up LiveStore DevTools
 
-You may have wondered: "If the data is persisted, _where_ is it?". If the data is somewhere on your file system, you _should_ be able to spin up a database viewer of your choice and inspect the local SQLite DB file. 
+You may have wondered: "If the data is persisted, _where_ is it?". If the data is somewhere on your file system, you _should_ be able to spin up a database viewer of your choice and inspect the local SQLite DB file.
 
 Unfortunately, that's not how OPFS works. While the SQLite files do exist _somewhere_ on your file system, they are hidden in the browser's internals and not easily accessible.
 
-That being said, there is a convenient way how you can actually see the data on your file system: Using [LiveStore DevTools](/reference/devtools/)!
+That being said, there is a convenient way how you can actually see the data on your file system: Using [LiveStore DevTools](/building-with-livestore/devtools)!
 
 :::note[LiveStore DevTools are a sponsor-only feature]
 
-Our goal is to grow the project in a [sustainable](/misc/sponsoring/#goal-sustainable-open-source) way (e.g. not rely on VC funding), that's why DevTools are currently a [sponsor-only](/misc/sponsoring/) feature. 
+Our goal is to grow the project in a [sustainable](/sustainable-open-source/sponsoring#goal-sustainable-open-source) way (e.g. not rely on VC funding), that's why DevTools are currently a [sponsor-only](/sustainable-open-source/sponsoring) feature.
 
 That being said, we still include them in this tutorial since you'll be able to use them without sponsorship for one week.
 
@@ -506,6 +525,6 @@ There are several tabs in the LiveStore DevTools:
 
 - **Database**: Browse the data that's currently in your DB, send SQL queries, export the database to your file system, and more.
 - **Queries**: Shows the last results of the currently active live queries.
-- **Events**: The [event log](/evaluation/event-sourcing/) that stores all the events emitted by your app.
+- **Events**: The [event log](/understanding-livestore/event-sourcing) that stores all the events emitted by your app.
 
 If you're curious, add and delete a few todos via the UI and observe what's happening in the three tabs.

package/docs/tutorial/4-sync-data-via-cloudflare/index.md

@@ -1,6 +1,6 @@
 # 4. Sync data to Cloudflare
 
-In this step, you're going to introduce a [sync](/reference/syncing/) backend. This sync backend will:
+In this step, you're going to introduce a [sync](/building-with-livestore/syncing) backend. This sync backend will:
 
 - Have a "live connection" (via WebSockets) to _all_ the clients that are running your app.
 - Propagate events to _all_ other clients whenever a particular client emits an event.
@@ -9,7 +9,7 @@ Notice how you'll achieve this by _only_ changing the data layer of your applica
 
 You won't need to touch the code that you've already written in `main.tsx` and `App.tsx`—all the syncing is handled by LiveStore under the hood without you needing to worry about it in your application code.
 
-You're going to implement the sync backend using [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Durable Objects](https://developers.cloudflare.com/durable-objects/), using the [@livestore/sync-cf](/reference/syncing/sync-provider/cloudflare/) package.
+You're going to implement the sync backend using [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Durable Objects](https://developers.cloudflare.com/durable-objects/), using the [@livestore/sync-cf](/sync-providers/cloudflare) package.
 
 ## Install the Cloudflare sync provider package
 

package/docs/tutorial/5-expand-business-logic/index.md

@@ -66,7 +66,7 @@ Next, add a `toggleTodo` function in `App.tsx` in which you're emitting the even
 
 function App() {
 
-  const { store } = useStore()
+  const store = useAppStore()
 
   const todos$ = queryDb(() => tables.todos.select())
 

package/docs/tutorial/6-persist-ui-state/index.md

@@ -5,9 +5,9 @@ As you saw in the beginning of the tutorial, the state of an application is typi
 - **App state**: State that represents the _application data_ a user needs to achieve their goals with your app. In your current case, that's the list of todos. App state _typically_ lives in the Cloud somewhere (in traditional apps, the Cloud is the source of truth for it; in local-first apps, the data is stored locally and backed up in the Cloud).
 - **UI state**: UI state that is only relevant for a particular browser session.
 
-Many websites have the problem of "losing UI state" on browser refreshes. This can be incredibly frustrating for users, especially when they've already invested a lot of time getting to a certain point in an app (e.g. filling out a form). Then, the site reloads for some reason and they have to start over! 
+Many websites have the problem of "losing UI state" on browser refreshes. This can be incredibly frustrating for users, especially when they've already invested a lot of time getting to a certain point in an app (e.g. filling out a form). Then, the site reloads for some reason and they have to start over!
 
-With LiveStore, this problem is easily solved: It allows you to persist _UI state_ (e.g. form inputs, active tabs, custom UI elements, and pretty much anything you'd otherwise manage via `React.useState`). This means users can always pick up exactly where they left off.
+With LiveStore, this problem is easily solved: It allows you to persist _UI state_ (e.g. form inputs, active tabs, custom UI elements, and pretty much anything you'd otherwise manage via `React.useState()`). This means users can always pick up exactly where they left off.
 
 ## Add another UI element
 
@@ -17,7 +17,7 @@ First, update `App.tsx` to look as follows:
 
 function App() {
 
-  const { store } = useStore()
+  const store = useAppStore()
 
   const todos$ = queryDb(() => tables.todos.select())
   const todos = store.useQuery(todos$)
@@ -175,7 +175,7 @@ export const tables = {
 On this table, you define:
 
 - A name for this client document.
-- The structure of the client document via `schema`; in your case: 
+- The structure of the client document via `schema`; in your case:
     - The current state of the `input` text field for adding a new todo.
     - The `filter` that'll be used to filter the todos according to their `completed` status.
 - Default values for this client document.
@@ -209,9 +209,9 @@ Here, both the event definition and materializer are automatically derived from
 
 ## Implement local state with LiveStore
 
-In this step, you need to add the local state for the tabbed UI element to the `App` component. Additionally, you're going to replace the `useState` hook that you currently use for the `input` state with LiveStore's approach as well.
+In this step, you need to add the local state for the tabbed UI element to the `<App>` component. Additionally, you're going to replace the `useState()` hook that you currently use for the `input` state with LiveStore's approach as well.
 
-Replace the `useState` usage for `input` and `filter` with LiveStore's [`useClientDocument`](/reference/framework-integrations/react-integration/#useclientdocument):
+Replace the `useState()` usage for `input` and `filter` with LiveStore's [`useClientDocument()`](/framework-integrations/react-integration#storeuseclientdocumenttable-id-options):
 
 ```diff title="src/App.tsx" lang="tsx"
 +const [{ input, filter }, setUiState, , uiState$] = store.useClientDocument(tables.uiState)
@@ -224,16 +224,16 @@ Replace the `useState` usage for `input` and `filter` with LiveStore's [`useClie
 -const updatedFilter = (filter: Filter) => store.commit(events.uiStateSet({ filter }))
 ```
 
-Don't forget to update the imports to include the `Filter` type and drop `useState`:
+Don't forget to update the imports to include the `Filter` type and drop `useState()`:
 
 ```diff title="src/App.tsx" lang="tsx"
 -import { useState } from 'react'
 
 ```
 
-`useClientDocument` persists the UI state inside LiveStore while giving you a React-friendly setter function similar to `useState`.
+`useClientDocument()` persists the UI state inside LiveStore while giving you a React-friendly setter function similar to `useState()`.
 
-Since you've renamed the functions to update the values of `input` and `filter` you need to adjust the parts of the `App` component where they are used:
+Since you've renamed the functions to update the values of `input` and `filter` you need to adjust the parts of the `<App>` component where they are used:
 
 - `setInput` → `updatedInput`
 - `setFilter` → `updatedFilter`
@@ -276,15 +276,15 @@ const todos$ = queryDb((
 const todos = store.useQuery(todos$)
 ```
 
-Here, `uiState$` comes from `useClientDocument`, ensuring that the todos query automatically reacts whenever the persisted UI state changes.
+Here, `uiState$` comes from `useClientDocument()`, ensuring that the todos query automatically reacts whenever the persisted UI state changes.
 
-This is the final code for the `App` component:
+This is the final code for the `<App>` component:
 
 ```tsx title="src/App.tsx"
 
 function App() {
 
-  const { store } = useStore()
+  const store = useAppStore()
 
   const [{ input, filter }, setUiState, , uiState$] = store.useClientDocument(tables.uiState)
 

package/docs/{evaluation → understanding-livestore}/design-decisions/index.md

@@ -1,4 +1,4 @@
-# Design Decisions
+# Design decisions
 
 ## Goals
 
@@ -11,7 +11,7 @@
 
 ## Major Design Decisions
 
-- Based on [event-sourcing](/evaluation/event-sourcing) (implying a read/write model separation)
+- Based on [event-sourcing](/understanding-livestore/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

package/docs/{evaluation → understanding-livestore}/event-sourcing/index.md

@@ -1,4 +1,4 @@
-# Event Sourcing
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/livestore",
-  "version": "0.4.0-dev.20",
+  "version": "0.4.0-dev.22",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -11,17 +11,17 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/common": "0.4.0-dev.20",
-    "@livestore/utils": "0.4.0-dev.20"
+    "@livestore/common": "0.4.0-dev.22",
+    "@livestore/utils": "0.4.0-dev.22"
   },
   "devDependencies": {
-    "@opentelemetry/sdk-trace-base": "2.0.1",
+    "@opentelemetry/sdk-trace-base": "2.2.0",
     "jsdom": "^26.1.0",
     "typescript": "5.9.2",
     "vite": "7.2.4",
     "vitest": "3.2.4",
-    "@livestore/adapter-web": "0.4.0-dev.20",
-    "@livestore/utils-dev": "0.4.0-dev.20"
+    "@livestore/utils-dev": "0.4.0-dev.22",
+    "@livestore/adapter-web": "0.4.0-dev.22"
   },
   "files": [
     "package.json",