@livestore/livestore 0.4.0-dev.18 → 0.4.0-dev.19

package/docs/reference/framework-integrations/react-integration/index.md

@@ -0,0 +1,906 @@
+# React integration for LiveStore
+
+While LiveStore is framework agnostic, the `@livestore/react` package provides a first-class integration with React.
+
+## Features
+
+- High performance
+- Fine-grained reactivity (using LiveStore's signals-based reactivity system)
+- Instant, synchronous query results (without the need for `useEffect` and `isLoading` checks)
+- Transactional state transitions (via `batchUpdates`)
+- Also supports Expo / React Native via `@livestore/adapter-expo`
+
+## API
+
+### `LiveStoreProvider`
+
+In order to use LiveStore with React, you need to wrap your application in a `LiveStoreProvider`.
+
+## `reference/framework-integrations/react/provider.tsx`
+
+```tsx filename="reference/framework-integrations/react/provider.tsx"
+
+const adapter = makeInMemoryAdapter()
+
+export const Root: FC<{ children: ReactNode }> = ({ children }) => (
+  <LiveStoreProvider schema={schema} adapter={adapter} batchUpdates={batchUpdates}>
+    {children}
+  </LiveStoreProvider>
+)
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text(),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+#### Logging
+
+`LiveStoreProvider` accepts optional logging configuration:
+
+## `reference/framework-integrations/react/provider-logging.tsx`
+
+```tsx filename="reference/framework-integrations/react/provider-logging.tsx"
+
+// ---cut---
+
+const adapter = makeInMemoryAdapter()
+
+const App: FC = () => <div>App</div>
+
+export const Root: FC<{ children: ReactNode }> = () => (
+  <LiveStoreProvider
+    schema={schema}
+    adapter={adapter}
+    batchUpdates={batchUpdates}
+    // Optional: swap the logger implementation
+    logger={Logger.prettyWithThread('app')}
+    // Optional: set minimum log level (use LogLevel.None to disable)
+    logLevel={LogLevel.Info}
+  >
+    <App />
+  </LiveStoreProvider>
+)
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text(),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+For scenarios where you have an existing store instance, you can manually create a `LiveStoreContext.Provider`:
+
+## `reference/framework-integrations/react/context-provider.tsx`
+
+```tsx filename="reference/framework-integrations/react/context-provider.tsx"
+
+declare const store: Store & ReactApi
+
+export const Root: FC<{ children: ReactNode }> = ({ children }) => (
+  <LiveStoreContext.Provider value={{ stage: 'running', store }}>{children}</LiveStoreContext.Provider>
+)
+```
+
+### useStore
+
+## `reference/framework-integrations/react/use-store.tsx`
+
+```tsx filename="reference/framework-integrations/react/use-store.tsx"
+
+export const MyComponent: FC = () => {
+  const { store } = useStore()
+
+  useEffect(() => {
+    store.commit(events.todoCreated({ id: '1', text: 'Hello, world!' }))
+  }, [store])
+
+  return <div>...</div>
+}
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text(),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+### useQuery
+
+## `reference/framework-integrations/react/use-query.tsx`
+
+```tsx filename="reference/framework-integrations/react/use-query.tsx"
+
+const query$ = queryDb(tables.todos.where({ completed: true }).orderBy('id', 'desc'), {
+  label: 'completedTodos',
+})
+
+export const CompletedTodos: FC = () => {
+  const { store } = useStore()
+  const todos = store.useQuery(query$)
+
+  return (
+    <div>
+      {todos.map((todo) => (
+        <div key={todo.id}>{todo.text}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text(),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+### useClientDocument
+
+## `reference/framework-integrations/react/use-client-document.tsx`
+
+```tsx filename="reference/framework-integrations/react/use-client-document.tsx"
+
+export const TodoItem: FC<{ id: string }> = ({ id }) => {
+  const { store } = useStore()
+  const [todo, updateTodo] = store.useClientDocument(tables.uiState, id)
+
+  return (
+    <button type="button" onClick={() => updateTodo({ text: 'Hello, world!' })}>
+      {todo.text}
+    </button>
+  )
+}
+```
+
+### `reference/framework-integrations/react/schema.ts`
+
+```ts filename="reference/framework-integrations/react/schema.ts"
+
+export const tables = {
+  todos: State.SQLite.table({
+    name: 'todos',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      text: State.SQLite.text(),
+      completed: State.SQLite.boolean({ default: false }),
+    },
+  }),
+  uiState: State.SQLite.clientDocument({
+    name: 'UiState',
+    schema: Schema.Struct({ text: Schema.String }),
+    default: { value: { text: '' } },
+  }),
+} as const
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'v1.TodoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String }),
+  }),
+} as const
+
+const materializers = State.SQLite.materializers(events, {
+  [events.todoCreated.name]: defineMaterializer(events.todoCreated, ({ id, text }) =>
+    tables.todos.insert({ id, text, completed: false }),
+  ),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+## Usage with ...
+
+### Vite
+
+LiveStore works with Vite out of the box.
+
+### Tanstack Start
+
+LiveStore works with Tanstack Start out of the box.
+
+### Expo / React Native
+
+LiveStore has a first-class integration with Expo / React Native via `@livestore/adapter-expo`.
+
+### Next.js
+
+Given various Next.js limitations, LiveStore doesn't yet work with Next.js out of the box.
+
+## Multi-Store
+
+The multi-store API enables managing multiple stores within a single React application. This is useful for:
+
+- **Partial data synchronization** - Load only the data you need, when you need it
+- **Multi-tenant applications** - Separate stores for each workspace, organization, or project (like Slack workspaces, Notion pages, or Linear teams)
+
+## `reference/framework-integrations/react/multi-store/minimal.tsx`
+
+```tsx filename="reference/framework-integrations/react/multi-store/minimal.tsx"
+
+const issueStoreOptions = (issueId: string) =>
+  storeOptions({
+    storeId: `issue-${issueId}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+  })
+
+export function App() {
+  const [registry] = useState(() => new StoreRegistry({ defaultOptions: { batchUpdates } }))
+  return (
+    <StoreRegistryProvider storeRegistry={registry}>
+      <IssueView />
+    </StoreRegistryProvider>
+  )
+}
+
+function IssueView() {
+  const store = useStore(issueStoreOptions('abc123'))
+  const [issue] = store.useQuery(queryDb(tables.issue.select()))
+  return <div>{issue?.title}</div>
+}
+```
+
+### `reference/framework-integrations/react/multi-store/schema.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
+
+// Event definitions
+export const events = {
+  issueCreated: Events.synced({
+    name: 'v1.IssueCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+  issueStatusChanged: Events.synced({
+    name: 'v1.IssueStatusChanged',
+    schema: Schema.Struct({
+      id: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+}
+
+// State definition
+export const tables = {
+  issue: State.SQLite.table({
+    name: 'issue',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      title: State.SQLite.text(),
+      status: State.SQLite.text(),
+    },
+  }),
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
+  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+:::caution[Experimental API]
+The Multi-Store API 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)
+:::
+
+### Core Concepts
+
+The multi-store API introduces four main primitives:
+
+- **StoreRegistry** - Manages and caches all store instances with automatic garbage collection
+- **useStore()** - Suspense-enabled hook for accessing individual store instances
+- **storeOptions()** - Type-safe way to define reusable store configurations
+
+Stores are cached by their `storeId` and automatically disposed after being unused for a configurable duration (`unusedCacheTime`)
+
+### Setting Up
+
+First, define your re-usable store configuration using `storeOptions()`:
+
+## `reference/framework-integrations/react/multi-store/store.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/store.ts"
+
+// Define reusable store configuration with storeOptions()
+// This helper provides type safety and can be reused across your app
+export const issueStoreOptions = (issueId: string) =>
+  storeOptions({
+    storeId: `issue-${issueId}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+  })
+```
+
+### `reference/framework-integrations/react/multi-store/schema.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
+
+// Event definitions
+export const events = {
+  issueCreated: Events.synced({
+    name: 'v1.IssueCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+  issueStatusChanged: Events.synced({
+    name: 'v1.IssueStatusChanged',
+    schema: Schema.Struct({
+      id: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+}
+
+// State definition
+export const tables = {
+  issue: State.SQLite.table({
+    name: 'issue',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      title: State.SQLite.text(),
+      status: State.SQLite.text(),
+    },
+  }),
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
+  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+Then create a `StoreRegistry` and provide it to your app:
+
+## `reference/framework-integrations/react/multi-store/App.tsx`
+
+```tsx filename="reference/framework-integrations/react/multi-store/App.tsx"
+
+export function App({ children }: { children: ReactNode }) {
+  const [storeRegistry] = useState(() => new StoreRegistry({ defaultOptions: { batchUpdates } }))
+
+  return <StoreRegistryProvider storeRegistry={storeRegistry}>{children}</StoreRegistryProvider>
+}
+```
+
+### Using Stores
+
+Use the `useStore()` hook to load or get a store instance. It suspends until the store is loaded:
+
+## `reference/framework-integrations/react/multi-store/IssueView.tsx`
+
+```tsx filename="reference/framework-integrations/react/multi-store/IssueView.tsx"
+
+export function IssueView({ issueId }: { issueId: string }) {
+  // useStore() suspends the component until the store is loaded
+  // If the same store was already loaded, it returns immediately
+  const issueStore = useStore(issueStoreOptions(issueId))
+
+  // Query data from the store
+  const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
+
+  if (!issue) return <div>Issue not found</div>
+
+  return (
+    <div>
+      <h3>{issue.title}</h3>
+      <p>Status: {issue.status}</p>
+    </div>
+  )
+}
+
+// Wrap with Suspense and ErrorBoundary for loading and error states
+export function IssueViewWithSuspense({ issueId }: { issueId: string }) {
+  return (
+    <ErrorBoundary fallback={<div>Error loading issue</div>}>
+      <Suspense fallback={<div>Loading issue...</div>}>
+        <IssueView issueId={issueId} />
+      </Suspense>
+    </ErrorBoundary>
+  )
+}
+```
+
+### `reference/framework-integrations/react/multi-store/schema.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
+
+// Event definitions
+export const events = {
+  issueCreated: Events.synced({
+    name: 'v1.IssueCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+  issueStatusChanged: Events.synced({
+    name: 'v1.IssueStatusChanged',
+    schema: Schema.Struct({
+      id: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+}
+
+// State definition
+export const tables = {
+  issue: State.SQLite.table({
+    name: 'issue',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      title: State.SQLite.text(),
+      status: State.SQLite.text(),
+    },
+  }),
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
+  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+### `reference/framework-integrations/react/multi-store/store.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/store.ts"
+
+// Define reusable store configuration with storeOptions()
+// This helper provides type safety and can be reused across your app
+export const issueStoreOptions = (issueId: string) =>
+  storeOptions({
+    storeId: `issue-${issueId}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+  })
+```
+
+### Multiple Instances
+
+You can create multiple instances of the same store type by using different `storeId` values:
+
+## `reference/framework-integrations/react/multi-store/IssueList.tsx`
+
+```tsx filename="reference/framework-integrations/react/multi-store/IssueList.tsx"
+
+function IssueCard({ issueId }: { issueId: string }) {
+  // Each call to useStore with a different storeId loads/gets a separate store instance
+  const issueStore = useStore(issueStoreOptions(issueId))
+  const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
+
+  if (!issue) return <div>Issue not found</div>
+
+  return (
+    <div>
+      <h4>{issue.title}</h4>
+      <p>Store ID: {issueStore.storeId}</p>
+      <p>Status: {issue.status}</p>
+    </div>
+  )
+}
+
+// Component that displays multiple independent store instances with shared error and loading states
+export function IssueList() {
+  const issueIds = ['issue-1', 'issue-2', 'issue-3']
+
+  return (
+    <div>
+      <h3>Issues</h3>
+      <ErrorBoundary fallback={<div>Error loading issues</div>}>
+        <Suspense fallback={<div>Loading issues...</div>}>
+          {issueIds.map((id) => (
+            <IssueCard key={id} issueId={id} />
+          ))}
+        </Suspense>
+      </ErrorBoundary>
+    </div>
+  )
+}
+```
+
+### `reference/framework-integrations/react/multi-store/schema.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
+
+// Event definitions
+export const events = {
+  issueCreated: Events.synced({
+    name: 'v1.IssueCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+  issueStatusChanged: Events.synced({
+    name: 'v1.IssueStatusChanged',
+    schema: Schema.Struct({
+      id: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+}
+
+// State definition
+export const tables = {
+  issue: State.SQLite.table({
+    name: 'issue',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      title: State.SQLite.text(),
+      status: State.SQLite.text(),
+    },
+  }),
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
+  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+### `reference/framework-integrations/react/multi-store/store.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/store.ts"
+
+// Define reusable store configuration with storeOptions()
+// This helper provides type safety and can be reused across your app
+export const issueStoreOptions = (issueId: string) =>
+  storeOptions({
+    storeId: `issue-${issueId}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+  })
+```
+
+Each store instance is completely isolated with its own data, event log, and synchronization state.
+
+### Preloading
+
+When you know a store will be needed soon, you can preload it in advance:
+
+## `reference/framework-integrations/react/multi-store/PreloadedIssue.tsx`
+
+```tsx filename="reference/framework-integrations/react/multi-store/PreloadedIssue.tsx"
+
+export function PreloadedIssue({ issueId }: { issueId: string }) {
+  const [showIssue, setShowIssue] = useState(false)
+  const storeRegistry = useStoreRegistry()
+
+  // Preload the store when user hovers (before they click)
+  const handleMouseEnter = () => {
+    storeRegistry.preload(issueStoreOptions(issueId))
+  }
+
+  return (
+    <div>
+      {!showIssue ? (
+        <button type="button" onMouseEnter={handleMouseEnter} onClick={() => setShowIssue(true)}>
+          Show Issue
+        </button>
+      ) : (
+        <ErrorBoundary fallback={<div>Error loading issue</div>}>
+          <Suspense fallback={<div>Loading issue...</div>}>
+            <IssueView issueId={issueId} />
+          </Suspense>
+        </ErrorBoundary>
+      )}
+    </div>
+  )
+}
+```
+
+### `reference/framework-integrations/react/multi-store/IssueView.tsx`
+
+```tsx filename="reference/framework-integrations/react/multi-store/IssueView.tsx"
+
+export function IssueView({ issueId }: { issueId: string }) {
+  // useStore() suspends the component until the store is loaded
+  // If the same store was already loaded, it returns immediately
+  const issueStore = useStore(issueStoreOptions(issueId))
+
+  // Query data from the store
+  const [issue] = issueStore.useQuery(queryDb(tables.issue.select().where({ id: issueId })))
+
+  if (!issue) return <div>Issue not found</div>
+
+  return (
+    <div>
+      <h3>{issue.title}</h3>
+      <p>Status: {issue.status}</p>
+    </div>
+  )
+}
+
+// Wrap with Suspense and ErrorBoundary for loading and error states
+export function IssueViewWithSuspense({ issueId }: { issueId: string }) {
+  return (
+    <ErrorBoundary fallback={<div>Error loading issue</div>}>
+      <Suspense fallback={<div>Loading issue...</div>}>
+        <IssueView issueId={issueId} />
+      </Suspense>
+    </ErrorBoundary>
+  )
+}
+```
+
+### `reference/framework-integrations/react/multi-store/schema.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/schema.ts"
+
+// Event definitions
+export const events = {
+  issueCreated: Events.synced({
+    name: 'v1.IssueCreated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+  issueStatusChanged: Events.synced({
+    name: 'v1.IssueStatusChanged',
+    schema: Schema.Struct({
+      id: Schema.String,
+      status: Schema.Literal('todo', 'done'),
+    }),
+  }),
+}
+
+// State definition
+export const tables = {
+  issue: State.SQLite.table({
+    name: 'issue',
+    columns: {
+      id: State.SQLite.text({ primaryKey: true }),
+      title: State.SQLite.text(),
+      status: State.SQLite.text(),
+    },
+  }),
+}
+
+const materializers = State.SQLite.materializers(events, {
+  'v1.IssueCreated': ({ id, title, status }) => tables.issue.insert({ id, title, status }),
+  'v1.IssueStatusChanged': ({ id, status }) => tables.issue.update({ status }).where({ id }),
+})
+
+const state = State.SQLite.makeState({ tables, materializers })
+
+export const schema = makeSchema({ events, state })
+```
+
+### `reference/framework-integrations/react/multi-store/store.ts`
+
+```ts filename="reference/framework-integrations/react/multi-store/store.ts"
+
+// Define reusable store configuration with storeOptions()
+// This helper provides type safety and can be reused across your app
+export const issueStoreOptions = (issueId: string) =>
+  storeOptions({
+    storeId: `issue-${issueId}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+  })
+```
+
+This warms up the cache so the store is ready when the user navigates to it.
+
+### StoreId Guidelines
+
+When creating `storeId` values:
+
+- **Use namespaces** - Prefix with the entity type (e.g., `workspace-abc123`, `issue-456`) to avoid collisions between different store types and improve debugging
+- **Globally unique** - Prefer globally unique IDs (e.g., nanoid) to prevent collisions
+- **Keep them stable** - The same entity should always use the same `storeId` across renders
+- **Sanitize user input** - If incorporating user data, be sure to validate/sanitize to prevent injection attacks
+- **Document your conventions** - Document your conventions and special IDs like `user-current` as they're part of your API contract
+
+### API Reference
+
+#### `storeOptions(options)`
+
+Defines reusable store configuration with type safety. Returns options that can be passed to `useStore()` or `registry.preload()`.
+
+Options:
+- `storeId` - Unique identifier for this store instance (required)
+- `schema` - The LiveStore schema (required)
+- `adapter` - The platform adapter (required)
+- `unusedCacheTime` - Time in milliseconds to keep unused stores in memory (default: 60_000 in browser, infinity in non-browser)
+- `boot` - Function called when the store is first loaded
+- `batchUpdates` - Function for batching React updates
+- And other `CreateStoreOptions`
+
+#### `new StoreRegistry(config?)`
+
+Creates a registry that manages store instances.
+
+Config:
+- `defaultOptions` - Default options applied to all stores (can be overridden per-store)
+
+#### `StoreRegistryProvider`
+
+React context provider that supplies the registry to components.
+
+Props:
+- `storeRegistry` - The registry instance (required)
+- `children` - React nodes (required)
+
+#### `useStore(options)`
+
+Hook that returns a store instance, suspending until it's loaded.
+
+- Throws a Promise during loading (for React Suspense)
+- Throws an Error if loading fails (for Error Boundaries)
+- Returns the loaded store when ready
+
+#### `useStoreRegistry()`
+
+Returns the current `StoreRegistry` from context. Useful for advanced operations like preloading.
+
+#### `registry.preload(options)`
+
+Starts loading a store without suspending. Returns a Promise that resolves when loading completes (or rejects on error). This is a fire-and-forget operation.
+
+### Complete Example
+
+See the <a href={`https://github.com/livestorejs/livestore/tree/${getBranchName()}/examples/web-multi-store`}>Multi-Store example</a> for a complete working application demonstrating various multi-store patterns.
+
+## Technical notes
+
+- `@livestore/react` uses `React.useState` under the hood for `useQuery` / `useClientDocument` to bind LiveStore's reactivity to React's reactivity. Some libraries are using `React.useExternalSyncStore` for similar purposes but using `React.useState` in this case is more efficient and all that's needed for LiveStore.
+- `@livestore/react` supports React Strict Mode.