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

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

@@ -7,26 +7,111 @@ While LiveStore is framework agnostic, the `@livestore/react` package provides a
 - High performance
 - Fine-grained reactivity (using LiveStore's signals-based reactivity system)
 - Instant, synchronous query results (without the need for `useEffect` and `isLoading` checks)
+- Supports multiple store instances
 - Transactional state transitions (via `batchUpdates`)
 - Also supports Expo / React Native via `@livestore/adapter-expo`
 
-## API
+## Core Concepts
 
-### `LiveStoreProvider`
+When using LiveStore in React, you'll primarily interact with these fundamental components:
 
-In order to use LiveStore with React, you need to wrap your application in a `LiveStoreProvider`.
+- [**`StoreRegistry`**](#new-storeregistryconfig) - Manages store instances with automatic caching and disposal
+- [**`<StoreRegistryProvider>`**](#storeregistryprovider) - React context provider that supplies the registry to components
+- [**`useStore()`**](#usestoreoptions) - Suspense-enabled hook for accessing store instances
 
-## `reference/framework-integrations/react/provider.tsx`
+Stores are cached by their `storeId` and automatically disposed after being unused for a configurable duration (`unusedCacheTime`).
 
-```tsx filename="reference/framework-integrations/react/provider.tsx"
+## `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 [storeRegistry] = useState(() => new StoreRegistry({ defaultOptions: { batchUpdates } }))
+  return (
+    <StoreRegistryProvider storeRegistry={storeRegistry}>
+      <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 })
+```
+
+## Setting Up
+
+### 1. Configure the Store
+
+Create a store configuration file that exports a custom hook wrapping [`useStore()`](#usestoreoptions):
+
+## `reference/framework-integrations/react/store.ts`
+
+```ts filename="reference/framework-integrations/react/store.ts"
 
 const adapter = makeInMemoryAdapter()
 
-export const Root: FC<{ children: ReactNode }> = ({ children }) => (
-  <LiveStoreProvider schema={schema} adapter={adapter} batchUpdates={batchUpdates}>
-    {children}
-  </LiveStoreProvider>
-)
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+  })
 ```
 
 ### `reference/framework-integrations/react/schema.ts`
@@ -67,46 +152,39 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-#### Logging
-
-`LiveStoreProvider` accepts optional logging configuration:
-
-```tsx
+The [`useStore()`](#usestoreoptions) hook accepts store configuration options and returns a store instance. It suspends while the store is loading, so components using it need to be wrapped in a `Suspense` boundary.
 
-<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>
-```
+### 2. Set Up the Registry
 
-For scenarios where you have an existing store instance, you can manually create a `LiveStoreContext.Provider`:
+Create a [`StoreRegistry`](#new-storeregistryconfig) and provide it via [`<StoreRegistryProvider>`](#storeregistryprovider). Wrap in a `<Suspense>` to handle loading states and a `<ErrorBoundary>` to handle errors:
 
-## `reference/framework-integrations/react/context-provider.tsx`
+## `reference/framework-integrations/react/provider.tsx`
 
-```tsx filename="reference/framework-integrations/react/context-provider.tsx"
+```tsx filename="reference/framework-integrations/react/provider.tsx"
 
-declare const store: Store & ReactApi
+export const Root: FC<{ children: ReactNode }> = ({ children }) => {
+  const [storeRegistry] = useState(() => new StoreRegistry())
 
-export const Root: FC<{ children: ReactNode }> = ({ children }) => (
-  <LiveStoreContext.Provider value={{ stage: 'running', store }}>{children}</LiveStoreContext.Provider>
-)
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong</div>}>
+      <Suspense fallback={<div>Loading LiveStore...</div>}>
+        <StoreRegistryProvider storeRegistry={storeRegistry}>{children}</StoreRegistryProvider>
+      </Suspense>
+    </ErrorBoundary>
+  )
+}
 ```
 
-### useStore
+### 3. Use the Store
+
+Components can now access the store via your custom hook:
 
 ## `reference/framework-integrations/react/use-store.tsx`
 
 ```tsx filename="reference/framework-integrations/react/use-store.tsx"
 
 export const MyComponent: FC = () => {
-  const { store } = useStore()
+  const store = useAppStore()
 
   useEffect(() => {
     store.commit(events.todoCreated({ id: '1', text: 'Hello, world!' }))
@@ -154,7 +232,24 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### useQuery
+### `reference/framework-integrations/react/store.ts`
+
+```ts filename="reference/framework-integrations/react/store.ts"
+
+const adapter = makeInMemoryAdapter()
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+```
+
+## Querying Data
+
+Use [`store.useQuery()`](#storeusequeryqueryable) to subscribe to reactive queries:
 
 ## `reference/framework-integrations/react/use-query.tsx`
 
@@ -165,7 +260,7 @@ const query$ = queryDb(tables.todos.where({ completed: true }).orderBy('id', 'de
 })
 
 export const CompletedTodos: FC = () => {
-  const { store } = useStore()
+  const store = useAppStore()
   const todos = store.useQuery(query$)
 
   return (
@@ -216,14 +311,31 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### useClientDocument
+### `reference/framework-integrations/react/store.ts`
+
+```ts filename="reference/framework-integrations/react/store.ts"
+
+const adapter = makeInMemoryAdapter()
+
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+  })
+```
+
+## Client Documents
+
+Use [`store.useClientDocument()`](#storeuseclientdocumenttable-id-options) for client-specific state:
 
 ## `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 store = useAppStore()
   const [todo, updateTodo] = store.useClientDocument(tables.uiState, id)
 
   return (
@@ -272,182 +384,31 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-## Usage with ...
+### `reference/framework-integrations/react/store.ts`
 
-### Vite
-
-LiveStore works with Vite out of the box.
-
-### Tanstack Start
-
-LiveStore works with Tanstack Start out of the box.
-
-#### Notes
-
-When using LiveStore with TanStack Start, it's crucial to place `LiveStoreProvider` in the correct location to avoid remounting on navigation.
-
-:::warn
-**Do NOT place `LiveStoreProvider` inside `shellComponent`**. The `shellComponent` can be re-rendered on navigation, causing LiveStore to remount and show the loading screen on every page transition.
-:::
-
-#### Correct pattern
-
-Use the `component` prop on `createRootRoute` for `LiveStoreProvider`:
-
-```tsx
-
-export const Route = createRootRoute({
-  shellComponent: RootShell,    // HTML structure only - NO state or providers
-  component: RootComponent,      // App shell - LiveStoreProvider goes HERE
-})
-
-// HTML document shell - keep this stateless
-function RootShell({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <head><HeadContent /></head>
-      <body>
-        {children}
-        <Scripts />
-      </body>
-    </html>
-  )
-}
-
-// App shell - persists across SPA navigation
-function RootComponent() {
-  return (
-    <LiveStoreProvider 
-      schema={schema} 
-      adapter={adapter} 
-      batchUpdates={batchUpdates}
-    >
-      <Outlet />
-    </LiveStoreProvider>
-  )
-}
-```
-
-#### Why this matters
-
-TanStack Start's `shellComponent` is designed for SSR HTML streaming and may be re-evaluated on server requests during navigation. When `LiveStoreProvider` is placed there:
-
-- The WebSocket connection is re-established on each navigation
-- The "Loading LiveStore" screen appears
-- All LiveStore state is re-initialized
-
-The `component` prop creates a React component that stays mounted during client-side SPA navigation, preserving LiveStore's connection and state.
-
-#### Debugging
-
-If you see the loading screen on every navigation, check your server logs. Multiple "Launching WebSocket" messages indicate `LiveStoreProvider` is remounting incorrectly.
-
-### 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:
+```ts filename="reference/framework-integrations/react/store.ts"
 
-- **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 adapter = makeInMemoryAdapter()
 
-const issueStoreOptions = (issueId: string) =>
-  storeOptions({
-    storeId: `issue-${issueId}`,
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
     schema,
-    adapter: makeInMemoryAdapter(),
+    adapter,
+    batchUpdates,
   })
-
-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.
+## Advanced Patterns
 
-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
+### Multiple Stores
 
-Stores are cached by their `storeId` and automatically disposed after being unused for a configurable duration (`unusedCacheTime`)
+You can have multiple stores within a single React application. This is useful for:
 
-### Setting Up
+- **Partial data synchronization** - Load only the data you need, when you need it
+- **Multi-tenant applications** - Separate stores for each workspace, organization, or team (like Slack workspaces or Linear teams)
 
-First, define your re-usable store configuration using `storeOptions()`:
+Use the [`storeOptions()`](#storeoptionsoptions) helper for type-safe, reusable configurations, and then create multiple instances for the same store configuration by using different `storeId` values:
 
 ## `reference/framework-integrations/react/multi-store/store.ts`
 
@@ -508,23 +469,6 @@ 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"
@@ -618,113 +562,11 @@ export const issueStoreOptions = (issueId: string) =>
   })
 ```
 
-### 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
+### Preloading Stores
 
-When you know a store will be needed soon, you can preload it in advance:
+When you know a store will be needed soon, preload it in advance to warm up the cache:
 
 ## `reference/framework-integrations/react/multi-store/PreloadedIssue.tsx`
 
@@ -734,9 +576,12 @@ export function PreloadedIssue({ issueId }: { issueId: string }) {
   const [showIssue, setShowIssue] = useState(false)
   const storeRegistry = useStoreRegistry()
 
-  // Preload the store when user hovers (before they click)
+  // Preload the store when the user hovers (before they click)
   const handleMouseEnter = () => {
-    storeRegistry.preload(issueStoreOptions(issueId))
+    storeRegistry.preload({
+      ...issueStoreOptions(issueId),
+      unusedCacheTime: 10_000, // Optionally override options
+    })
   }
 
   return (
@@ -850,69 +695,243 @@ export const issueStoreOptions = (issueId: string) =>
   })
 ```
 
-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
+- **Valid characters** - Only alphanumeric characters, underscores (`_`), and hyphens (`-`) are allowed (regex: `/^[a-zA-Z0-9_-]+$/`)
 - **Globally unique** - Prefer globally unique IDs (e.g., nanoid) to prevent collisions
+- **Use namespaces** - Prefix with the entity type (e.g., `workspace-abc123`, `issue-456`) to avoid collisions and easier identification when debugging
 - **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
+- **Sanitize user input** - If incorporating user data, validate/sanitize to prevent injection attacks
+- **Document your conventions** - Document special IDs like `user-current` as they're part of your API contract
+
+### Logging
+
+You can customize the logger and log level for debugging:
+
+## `reference/framework-integrations/react/store-with-logging.ts`
+
+```ts filename="reference/framework-integrations/react/store-with-logging.ts"
+
+const adapter = makeInMemoryAdapter()
+
+// ---cut---
+export const useAppStore = () =>
+  useStore({
+    storeId: 'app-root',
+    schema,
+    adapter,
+    batchUpdates,
+    // Optional: swap the logger implementation
+    logger: Logger.prettyWithThread('app'),
+    // Optional: set minimum log level (use LogLevel.None to disable)
+    logLevel: LogLevel.Info,
+  })
+```
+
+### `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 })
+```
+
+Use `LogLevel.None` to disable logging entirely.
+
+## API Reference
 
-### API Reference
+### `storeOptions(options)`
 
-#### `storeOptions(options)`
+Helper for defining reusable store options with full type inference. Returns options that can be passed to [`useStore()`](#usestoreoptions) or [`storeRegistry.preload()`](#storeregistrypreloadoptions).
 
-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
+- `schema` - The LiveStore schema
+- `adapter` - The platform adapter
+- `unusedCacheTime?` - Time in ms to keep unused stores in cache (default: `60_000` in browser, `Infinity` in non-browser environments)
+- `batchUpdates?` - Function for batching React updates (recommended)
+- `boot?` - Function called when the store is loaded
+- `onBootStatus?` - Callback for boot status updates
+- `context?` - User-defined context for dependency injection
+- `syncPayload?` - Payload sent to sync backend (e.g., auth tokens)
+- `syncPayloadSchema?` - Schema for type-safe sync payload validation
+- `confirmUnsavedChanges?` - Register beforeunload handler (default: `true`, web only)
+- `logger?` - Custom logger implementation
+- `logLevel?` - Log level (e.g., `LogLevel.Info`, `LogLevel.Debug`, `LogLevel.None`)
+- `otelOptions?` - OpenTelemetry configuration (`{ tracer, rootSpanContext }`)
+- `disableDevtools?` - Whether to disable devtools (`boolean | 'auto'`, default: `'auto'`)
+- `debug?` - Debug options (`{ instanceId?: string }`)
+
+### `useStore(options)`
+
+Returns a store instance augmented with hooks ([`store.useQuery()`](#storeusequeryqueryable) and [`store.useClientDocument()`](#storeuseclientdocumenttable-id-options)) for reactive queries.
+
+- Suspends until the store is loaded.
+- Throws an error if loading fails.
+- Store gets cached by its `storeId` in the [`StoreRegistry`](#new-storeregistryconfig). Multiple calls with the same `storeId` return the same store instance.
+- Store is cached as long as it's being used, and after `unusedCacheTime` expires (default `60_000` ms in browser, `Infinity` in non-browser)
+- Default store options can be configured in [`StoreRegistry`](#new-storeregistryconfig) constructor.
+- Store options are only applied when the store is loaded. Subsequent calls with different options will not affect the store if it's already loaded and cached in the registry.
+
+### `store.commit(...events)` / `store.commit(txnFn)`
+
+Commits events to the store. Supports multiple calling patterns:
+
+- `store.commit(...events)` - Commit one or more events
+- `store.commit(txnFn)` - Commit events via a transaction function
+- `store.commit(options, ...events)` - Commit with options
+- `store.commit(options, txnFn)` - Options with transaction function
 
 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`
+- `skipRefresh` - Skip refreshing reactive queries after commit (advanced)
+
+### `store.useQuery(queryable)`
+
+Subscribes to a reactive query. Re-renders the component when the result changes.
+
+- Takes any `Queryable`: `QueryBuilder`, `LiveQueryDef`, `SignalDef`, or `LiveQuery` instance
+- Returns the query result
+
+### `store.useClientDocument(table, id?, options?)`
+
+React.useState-like hook for client-document tables.
+
+- Returns `[row, setRow, id, query$]` tuple
+- Works only with tables defined via `State.SQLite.clientDocument()`
+- If the table has a default id, the `id` argument is optional
 
-#### `new StoreRegistry(config?)`
+### `new StoreRegistry(config?)`
 
-Creates a registry that manages store instances.
+Creates a registry that coordinates store loading, caching, and retention.
 
 Config:
-- `defaultOptions` - Default options applied to all stores (can be overridden per-store)
+- `defaultOptions?` - Default options that are applied to all stores when they are loaded.:
+  - `batchUpdates?` - Function for batching React updates
+  - `unusedCacheTime?` - Cache time for unused stores
+  - `disableDevtools?` - Whether to disable devtools
+  - `confirmUnsavedChanges?` - beforeunload confirmation
+  - `otelOptions?` - OpenTelemetry configuration
+  - `debug?` - Debug options
+- `runtime?` - Effect runtime for registry operations
 
-#### `StoreRegistryProvider`
+### `<StoreRegistryProvider>`
 
-React context provider that supplies the registry to components.
+React context provider that makes a [`StoreRegistry`](#new-storeregistryconfig) available to descendant components.
 
 Props:
-- `storeRegistry` - The registry instance (required)
-- `children` - React nodes (required)
+- `storeRegistry` - The registry instance
+
+### `useStoreRegistry(override?)`
+
+Hook that returns the [`StoreRegistry`](#new-storeregistryconfig) provided by the nearest [`<StoreRegistryProvider>`](#storeregistryprovider) ancestor, or the `override` if provided.
+
+### `storeRegistry.preload(options)`
+
+Loads a store (without suspending) to warm up the cache. Returns a Promise that resolves when loading completes. This is a fire-and-forget operation useful for warming up the cache.
+
+## Framework-Specific Notes
+
+### Vite
+
+LiveStore works with Vite out of the box.
+
+### Tanstack Start
+
+LiveStore works with Tanstack Start out of the box.
+
+#### Provider Placement
+
+When using LiveStore with TanStack Start, place [`<StoreRegistryProvider>`](#storeregistryprovider) in the correct location to avoid remounting on navigation.
+
+:::caution
+**Do NOT place `<StoreRegistryProvider>` inside `shellComponent`**. The `shellComponent` can be re-rendered on navigation, causing LiveStore to remount and show the loading screen on every page transition.
+:::
+
+Use the `component` prop on `createRootRoute` for `<StoreRegistryProvider>`:
+
+```tsx
 
-#### `useStore(options)`
+export const Route = createRootRoute({
+  shellComponent: RootShell,    // HTML structure only - NO state or providers
+  component: RootComponent,      // App shell - StoreRegistryProvider goes HERE
+})
 
-Hook that returns a store instance, suspending until it's loaded.
+// HTML document shell - keep this stateless
+function RootShell({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head><HeadContent /></head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
 
-- Throws a Promise during loading (for React Suspense)
-- Throws an Error if loading fails (for Error Boundaries)
-- Returns the loaded store when ready
+// App shell - persists across SPA navigation
+function RootComponent() {
+  const [storeRegistry] = useState(() => new StoreRegistry())
 
-#### `useStoreRegistry()`
+  return (
+    <Suspense fallback={<div>Loading LiveStore...</div>}>
+      <StoreRegistryProvider storeRegistry={storeRegistry}>
+        <Outlet />
+      </StoreRegistryProvider>
+    </Suspense>
+  )
+}
+```
 
-Returns the current `StoreRegistry` from context. Useful for advanced operations like preloading.
+TanStack Start's `shellComponent` is designed for SSR HTML streaming and may be re-evaluated on server requests during navigation. When `<StoreRegistryProvider>` is placed there, the WebSocket connection is re-established and all LiveStore state is re-initialized on each navigation.
 
-#### `registry.preload(options)`
+If you see the loading screen on every navigation, check your server logs for multiple "Launching WebSocket" messages.
 
-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.
+### Expo / React Native
+
+LiveStore has a first-class integration with Expo / React Native via `@livestore/adapter-expo`. See the [Expo Adapter documentation](/platform-adapters/expo-adapter).
+
+### Next.js
+
+Given various Next.js limitations, LiveStore doesn't yet work with Next.js out of the box.
 
 ### 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
+## 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` uses `React.useState()` under the hood for `useQuery()` / `useClientDocument()` to bind LiveStore's reactivity to React's reactivity. Some libraries use `React.useSyncExternalStore()` for similar purposes but `React.useState()` is more efficient for LiveStore's architecture.
 - `@livestore/react` supports React Strict Mode.