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

package/docs/sustainable-open-source/contributing/docs/index.md

@@ -0,0 +1,94 @@
+# Docs
+
+Please follow LiveStore's [guiding principles](/sustainable-open-source/contributing/info#guiding-principles) when writing docs.
+
+## Writing style
+
+This project broadly tries to follow the [Prisma docs style guide](https://www.prisma.io/docs/about/style-guide/writing-style).
+
+## Use regular sentence casing for titles of navigation item, pages and sections
+
+All titles for navigation items, pages and sections are using regular sentence casing. This means that only the first word and proper nouns (e.g. "Cloudflare Workers" or "Cloudflare Durable Objects") are capitalized.
+
+### Example 1
+
+Good:
+
+```md
+## This is the title of this section
+```
+
+Bad:
+
+```md
+## This is the Title of this Section
+```
+
+### Example 2
+
+Good:
+
+```md
+## This pages is about Cloudflare Workers
+```
+
+Bad:
+
+```md
+##  This pages is about cloudflare workers
+```
+
+## Create proper frontmatter for every page
+
+Frontmatter is YAML metadata at the start of MD/MDX files (between `---` markers) that controls page rendering, navigation, and SEO.
+
+### Required fields
+
+- **`title`**: Page title used for the browser tab, search results, and page heading. Always required.
+- **`description`**: Brief summary (150-160 characters) used for search snippets and social previews. Highly recommended for SEO.
+
+### Optional fields
+
+- **`sidebar`**: Controls sidebar navigation
+  - `label`: Custom sidebar label (defaults to `title`)
+  - `order`: Numeric sort order (lower numbers appear first)
+
+### SEO impact
+
+The `title` and `description` fields directly impact SEO:
+- `title` becomes the `<title>` tag and search result headline
+- `description` becomes the `<meta name="description">` tag and search snippet
+- Both are used for Open Graph and Twitter Card previews
+- OG images are auto-generated at `/og/{slug}.png` using these fields
+
+### Examples
+
+Minimal (title only):
+```yaml
+---
+title: Getting started with LiveStore + React
+---
+```
+
+With description and sidebar:
+```yaml
+---
+title: Getting started with LiveStore + React
+description: How to use LiveStore with React on the web.
+sidebar:
+  label: React web
+  order: 1
+---
+```
+
+## Snippets
+
+For snippet guidelines, see: `/contributor-docs/docs/snippets.md`
+
+## Deploying the docs
+
+- Run `direnv exec . mono docs deploy` to build and deploy the documentation to the dev domain (`https://dev.docs.livestore.dev`).
+- Passing `--prod` targets the production domain (`https://docs.livestore.dev`) when you are on `main` (otherwise the command deploys using a branch alias).
+- Use `--site=<slug>` if you need to override the default Netlify site name.
+- Add `--purge-cdn` when you need to invalidate Netlify's CDN cache after deploying; this ensures new edge handlers or content-negotiation changes take effect immediately.
+- CI automatically builds and deploys the docs: `main` updates `https://docs.livestore.dev`, `dev` updates `https://dev.docs.livestore.dev`, and feature branches publish to the dev domain behind a branch alias.

package/docs/{contributing/contributing → sustainable-open-source/contributing/info}/index.md

@@ -1,4 +1,4 @@
-# Contributing
+# Info
 
 ## Before contributing
 

package/docs/{contributing → sustainable-open-source/contributing}/monorepo/index.md

@@ -60,7 +60,7 @@ cd livestore
 - [Vitest](https://vitest.dev/)
 - [Playwright](https://playwright.dev/)
 - [OpenTelemetry](https://opentelemetry.io/)
-- [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (included as git subtree) - see [wa-sqlite management](../../../../contributor-docs/wa-sqlite-management.md)
+- [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (included as git subtree) - see [wa-sqlite management](../../../../../../contributor-docs/wa-sqlite-management.md)
 - [Nix](https://zero-to-nix.com/)
 - [Direnv](https://direnv.net/)
 - [devenv](https://devenv.sh)

package/docs/{misc → sustainable-open-source}/sponsoring/index.md

@@ -31,7 +31,7 @@ Thank you! 🧡
 - [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
+## 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.
@@ -54,11 +54,11 @@ Thank you! 🧡
 -	**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
+## Sponsor benefits
 
 You can access your sponsor benefits via the [Sponsor dashboard](https://livestore.dev/sponsor).
 
-- [LiveStore Devtools](/reference/devtools) License
+- [LiveStore Devtools](/building-with-livestore/devtools) License
 - Access to
   - Sponsor-only Discord channels
   - LiveStore Office Hours
@@ -97,7 +97,7 @@ Yes, please reach out via Discord.
 
 Yes, there are many ways to support LiveStore:
 
-- Become a [contributor / maintainer](/contributing/contributing)
+- Become a [contributor / maintainer](/sustainable-open-source/contributing/info)
 - Help other community members (e.g. via Discord)
 - Spread the word
   - Give talks, write blog posts, post on social media, ...

package/docs/{reference/syncing/sync-provider → sync-providers}/cloudflare/index.md

@@ -7,7 +7,7 @@ The `@livestore/sync-cf` package provides a comprehensive LiveStore sync provide
 <div class="d2-full-width">
 
 ```d2
-...@../../../../base.d2
+...@../../../../src/content/base.d2
 
 direction: right
 
@@ -55,11 +55,11 @@ Key responsibilities:
 pnpm add @livestore/sync-cf
 ```
 
-## Transport Modes
+## Transport modes
 
 The sync provider supports three transport protocols, each optimized for different use cases:
 
-### WebSocket Transport (Recommended)
+### WebSocket transport (Recommended)
 
 Real-time bidirectional communication with automatic reconnection and live pull support.
 
@@ -72,7 +72,7 @@ export const syncBackend = makeWsSync({
 })
 ```
 
-### HTTP Transport
+### HTTP transport
 
 HTTP-based sync with polling for live updates. Requires the `enable_request_signal` compatibility flag.
 
@@ -88,7 +88,7 @@ export const syncBackend = makeHttpSync({
 })
 ```
 
-### Durable Object RPC Transport
+### Durable Object RPC transport
 
 Direct RPC communication between Durable Objects (internal use by `@livestore/adapter-cloudflare`).
 
@@ -108,7 +108,7 @@ export const syncBackend = makeDoRpcSync({
 })
 ```
 
-## Client API Reference
+## Client API reference
 
 ### `makeWsSync(options)`
 
@@ -352,7 +352,7 @@ export const storeIdFromRequest = (request: CfTypes.Request) => {
 }
 ```
 
-## Server API Reference
+## Server API reference
 
 ### `makeDurableObject(options)`
 
@@ -536,7 +536,7 @@ if (searchParams !== undefined) {
 
 ## Configuration
 
-### Wrangler Configuration
+### Wrangler configuration
 
 Configure your `wrangler.toml` for sync backend deployment (default: DO SQLite storage):
 
@@ -566,7 +566,7 @@ database_name = "livestore-sync"
 database_id = "your-database-id"
 ```
 
-### Environment Variables
+### Environment variables
 
 Required environment bindings:
 
@@ -579,7 +579,7 @@ export interface Env {
 }
 ```
 
-## Transport Protocol Details
+## Transport protocol details
 
 LiveStore identifies sync requests purely by search parameters; the request path does not matter. Use `matchSyncRequest(request)` to detect sync traffic.
 
@@ -600,7 +600,7 @@ Notes:
 - For `transport=ws`, if the request is not a WebSocket upgrade, the backend returns `426 Upgrade Required`.
 - `transport='do-rpc'` is internal for Durable Object RPC and not exposed via URL parameters.
 
-## Data Storage
+## Data storage
 
 By default, events are stored in the Durable Object’s SQLite with tables following the pattern:
 ```
@@ -609,7 +609,7 @@ eventlog_{PERSISTENCE_FORMAT_VERSION}_{storeId}
 
 You can opt into D1 with the same table shape. The persistence format version is automatically managed and incremented when the storage schema changes.
 
-### Storage Engines
+### Storage engines
 - DO SQLite (default)
   - Pros: easiest deploy (no D1), data co-located with the DO, lowest latency
   - Cons: not directly inspectable outside the DO; operational tooling must go through the DO
@@ -632,7 +632,7 @@ npx wrangler d1 create livestore-sync
 npx wrangler d1 migrations apply livestore-sync
 ```
 
-## Local Development
+## Local development
 
 Run locally with Wrangler:
 
@@ -646,7 +646,7 @@ npx wrangler dev
 
 ## Examples
 
-### Basic WebSocket Client
+### Basic WebSocket client
 
 ## `reference/syncing/cloudflare/basic-ws-client.ts`
 
@@ -714,7 +714,7 @@ const state = State.SQLite.makeState({ tables, materializers })
 export const schema = makeSchema({ events, state })
 ```
 
-### Custom Worker with Authentication
+### Custom worker with authentication
 
 ## `reference/syncing/cloudflare/worker-auth.ts`
 

package/docs/{reference/syncing/sync-provider → sync-providers}/electricsql/index.md

@@ -40,7 +40,7 @@ The API proxy has dual responsibilities:
 - **Authentication**: Implements your custom auth logic
 - **Database Management**: Initializes tables and manages connections
 
-## Client Setup
+## Client setup
 
 Basic usage in your worker/server code:
 
@@ -54,11 +54,11 @@ const _backend = makeSyncBackend({
 })
 ```
 
-## API Proxy Implementation
+## API proxy implementation
 
 ElectricSQL requires an API proxy on your server to handle authentication and database operations. Your proxy needs two endpoints:
 
-### Minimal Implementation Example
+### Minimal implementation example
 
 ## `reference/syncing/sync-provider/electricsql/api-proxy.ts`
 
@@ -114,7 +114,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Important Considerations
+### Important considerations
 
 - **Database Setup**: Ensure your Postgres database is configured for Electric
 - **Authentication**: Implement proper auth checks in your proxy

package/docs/{reference/syncing/sync-provider → sync-providers}/s2/index.md

@@ -38,7 +38,7 @@ The API proxy handles:
 - **S2 Stream Management**: Creates basins and streams as needed
 - **S2 Request Translation**: Converts LiveStore sync operations to authenticated S2 API calls
 
-## Client Setup
+## Client setup
 
 Basic usage in your worker/server code:
 
@@ -52,7 +52,7 @@ const _backend = makeSyncBackend({
 })
 ```
 
-## API Proxy Implementation
+## API proxy implementation
 
 S2 requires authentication and stream management that can't be handled directly from the browser. You'll need to implement an API proxy on your server that:
 
@@ -62,7 +62,7 @@ S2 requires authentication and stream management that can't be handled directly
 
 Your proxy needs three endpoints:
 
-### Using Helper Functions
+### Using helper functions
 
 The `@livestore/sync-s2` package provides helper functions to simplify the proxy implementation:
 
@@ -152,7 +152,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Cursor Semantics
+### Cursor semantics
 
 The S2 sync provider uses a cursor that represents the **last processed record**:
 - The cursor points to the last S2 sequence number we've seen
@@ -160,7 +160,7 @@ The S2 sync provider uses a cursor that represents the **last processed record**
 - The helper functions automatically handle the `+1` conversion: `seq_num = cursor + 1`
 - When starting from the beginning, cursor is `'from-start'` which maps to `seq_num = 0`
 
-### Important Considerations
+### Important considerations
 
 - **Stream provisioning**: The helper functions provide `ensureBasin()` and `ensureStream()` to handle creation automatically.
 - **Error handling**: The helpers include fallback responses (`emptyBatchResponse()`, `sseKeepAliveResponse()`) to maintain stream continuity during errors.
@@ -168,7 +168,7 @@ The S2 sync provider uses a cursor that represents the **last processed record**
 - **Rate limiting**: Consider implementing rate limiting to protect your S2 quota.
 - **Response helpers**: Use the provided response helpers (`successResponse()`, `errorResponse()`) for consistent API responses.
 
-## Live Pull (SSE)
+## Live pull (SSE)
 
 S2 provider supports live pulls over Server-Sent Events (SSE). When `live: true` is passed to `pull`, the client:
 - Immediately emits one page (possibly empty) with `pageInfo: NoMore`.
@@ -177,13 +177,13 @@ S2 provider supports live pulls over Server-Sent Events (SSE). When `live: true`
   - `event: ping` → ignored; keeps the stream alive.
   - `event: error` → mapped to `InvalidPullError`.
 
-## Implementation Notes
+## Implementation notes
 
-### Data Storage & Encoding
+### Data storage & encoding
 
 LiveStore leverages S2 streams for durable event storage. Understanding the mapping between LiveStore concepts and S2 primitives helps developers comprehend the persistence layer, though direct manipulation is discouraged.
 
-#### LiveStore → S2 Mapping
+#### LiveStore → S2 mapping
 
 **Store to Stream**: Each LiveStore `storeId` maps to exactly one S2 stream. The stream name is derived from the `storeId` after sanitization to meet S2 naming requirements.
 
@@ -199,7 +199,7 @@ LiveStore leverages S2 streams for durable event storage. Understanding the mapp
 
 <Code lang="json" code={CODE.recordStructureExample} title="S2 Record Example" />
 
-#### Sequence Number Handling
+#### Sequence number handling
 
 **LiveStore and S2 maintain completely independent sequence numbering systems**:
 
@@ -211,7 +211,7 @@ These are **two separate numbering systems** that happen to both start at 0. Whi
 - Uses S2's seq_num only for querying records from the stream (e.g., "read from position X")
 - Never relies on S2's seq_num for LiveStore's logical event ordering
 
-#### Technical Details
+#### Technical details
 
 **Format**: The provider uses `s2-format: raw` when communicating with S2, treating record bodies as UTF-8 JSON strings.
 
@@ -219,7 +219,7 @@ These are **two separate numbering systems** that happen to both start at 0. Whi
 
 **Batch Operations**: Multiple events can be pushed in a single batch, with each event becoming a separate S2 record while maintaining order.
 
-#### Important Note
+#### Important note
 
 **Direct stream manipulation is strongly discouraged**. Always interact with S2 streams through LiveStore's sync provider to ensure:
 - Proper event encoding/decoding

package/docs/tutorial/0-welcome/index.md

@@ -16,7 +16,7 @@ The goal of the tutorial is to _educate_. It reduces as much noise as possible s
 
 ### Useful knowledge
 
-While the tutorial is aimed at LiveStore newcomers, it will be helpful to have some knowledge in basic areas of web development, such as of [React](https://react.dev/), [TypeScript](https://www.typescriptlang.org/) and [event-driven architectures](/evaluation/how-livestore-works/#event-sourcing).
+While the tutorial is aimed at LiveStore newcomers, it will be helpful to have some knowledge in basic areas of web development, such as of [React](https://react.dev/), [TypeScript](https://www.typescriptlang.org/) and [event-driven architectures](/overview/how-livestore-works#event-sourcing).
 
 ### Technical setup
 

package/docs/tutorial/1-setup-starter-project/index.md

@@ -25,7 +25,7 @@ Once you've downloaded the project, you can navigate to the project directory an
 The project currently is set up as follows:
 - Minimal project created via [`vite create`](https://vite.dev/guide/#scaffolding-your-first-vite-project) using React and TypeScript.
 - Using [Tailwind CSS](https://tailwindcss.com/) for styling.
-- Has basic functionality for adding and deleting todos via local [`React.useState`](https://react.dev/learn/state-a-components-memory).
+- Has basic functionality for adding and deleting todos via local [`React.useState()`](https://react.dev/learn/state-a-components-memory).
 
 ## Understand the current project state
 
@@ -80,8 +80,8 @@ function App() {
 
   return (
     // Render input text field and todo list ...
-    // ... and invoke `addTodo` and `deleteTodo` 
-    // ... when the buttons are clicked. 
+    // ... and invoke `addTodo` and `deleteTodo`
+    // ... when the buttons are clicked.
   )
 }
 ```
@@ -98,8 +98,8 @@ The "problem" with this code is that the todo items are not _persisted_, meaning
 - the page is refreshed in the browser.
 - the development server is restarted.
 
-In the next chapters, you'll learn how to persist the todos in the list, so that they'll "survive" both actions. 
+In the next chapters, you'll learn how to persist the todos in the list, so that they'll "survive" both actions.
 
-Even more: They will not only persist, they will automatically sync across multiple browsers tabs/windows, and even across devices—without you needing to think about the syncing logic and managing remote state. 
+Even more: They will not only persist, they will automatically sync across multiple browsers tabs/windows, and even across devices—without you needing to think about the syncing logic and managing remote state.
 
 That's the power of LiveStore!