This page helps coding agents build with Rindle. The same introduction and getting started guide serve human readers and agents.
Rindle maintains query results as data changes. The engine is the shared foundation. A database runtime captures writes, and a synced app adds authorization, subscriptions, and optimistic browser writes.
The Agents on live data guide covers a different task: an agent inside your application that reacts to query changes.
Start with the task
Before choosing packages, identify where the data lives and which process can write it. Keep the existing application framework unless the task requires a new project.
| Task | Read first | Then read |
|---|---|---|
| Maintain views in one browser tab | Browser engine | TypeScript queries, change model |
| Choose remote, normalized, or optimistic browser data | Browser client chooser | Backends, optimistic client |
| Embed SQLite with live queries in Rust | Replica runtime | Rust queries, change model |
| Supply row changes to the raw Rust engine | Rust quickstart | How it works, change model |
| Maintain live views over SQLite in Node | Backends | Replica runtime, schema |
| Build a synced application | App scaffold | Architecture, schema, client, mutators |
| Add sync to an existing application | Manual app setup | API server, authorization |
| Run ordinary SQL from a server or script | Rindle SQL | SQL CLI, schema and migrations |
| Keep PostgreSQL as the write authority | Postgres source | API server, mutators |
| Keep a server query warm between requests | Pinned queries | API server |
| Add TanStack Start, route preloads, or server rendering | TanStack Start | Preloads, server rendering |
| Add local state to a synced app | Local-only tables | Persist local tables |
The Postgres source is a preview. Its page states the supported query operations, deployment limits, and open release gates.
Fetch only the relevant documentation
The documentation index lists pages with descriptions. Every docs
page has a Markdown version at /docs/<slug>.md. For example,
/docs/client.md contains the browser client guide without the
site navigation.
For tasks that need many related pages, these bundles are available:
- Engine and runtime documentation.
- Synced-app documentation.
- The full site, including product pages and blog posts.
The site groups documentation into Onboarding, Guides, and Reference. Each section covers multiple integrations. The focused bundles are reading aids. The API map covers the full surface, and individual pages state each feature’s requirements.
- Read the introduction and the task’s first guide.
- Read the API map to identify the packages involved.
- Fetch the query, mutation, or runtime reference for the code you will change.
- Read the linked limits before selecting a topology or query shape.
- Use the installed package version and its types to resolve an API mismatch.
Keep these distinctions clear
A live query differs from a SQL request. A registered query stays current
within the engine’s supported query shapes. @rindle/sql-client runs SQL and
returns a response. A SQL expression does not automatically become a live query.
The browser has several client compositions. @rindle/client supplies shared
APIs. createWasmStore runs locally. createRemoteStore receives flat query
results without WASM and needs a compatible server. createNormalizedStore
maintains local queries over server rows. createRindleClient supplies the
standard daemon integration with leases, reconnect handling, and optimistic writes.
Use the chooser before selecting a transport.
The embedded database differs from the raw engine. rindle-replica captures
ordinary SQL writes and manages query workers. The core rindle graph consumes
explicit changes. A Db, graph, or Cluster coordinator belongs to one thread. A Cluster owns
independent worker graphs and sends events through a channel that must be drained.
Cluster changes can precede commit; stage them until worker progress confirms the
transaction. A Db query remains registered until Query::destroy, even if its
handle is dropped.
The schema source depends on the store. A standalone in-memory store defines
its tables in TypeScript. A database-backed application defines tables through
SQL migrations and generates its TypeScript schema. Edit migrations and the
application’s schema extensions. Do not edit schema.gen.ts.
The server authorizes queries and writes. A synced browser sends named queries and their arguments to the API authority. It does not receive the database token. Server-rendered reads use the same authorization rules as browser reads.
Optimistic writes are predictions. An isomorphic mutator runs locally and on the server. Its local execution must support replay. Server-only operations and external side effects belong in the documented server hooks.
Persistence has several scopes. Database persistence, local-table persistence, and pinned server queries have separate lifecycles. A warm query does not imply durable browser storage or offline access to every row.
Check the result
For a live query, compare the maintained result with a fresh query after the same writes. This is Rindle’s core contract: view-after-write == fresh-query.
For a synced application, cover local prediction, server confirmation, rejected writes, and a second client’s updates. The testing guide provides the corresponding harnesses.
For code inside the Rindle repository, read its AGENTS.md and CLAUDE.md.
Those files describe engine development and repository checks. This guide
describes applications that use Rindle.