Introduction
What locel is, what is documented, and what is built.
locel is a local-first sync engine for TypeScript. Writes apply locally and survive a reload. The server stays the authority. Conflicts are detected per field, against the version the user was actually looking at.
How this documentation is written
The documentation comes first. A page here describes an API that has been designed and agreed, not necessarily one that exists. Nothing is built until its page reads well, because a surface that cannot be explained in a paragraph is a surface that will be explained in a support thread instead.
Every page carries a status:
- Documented — the API is agreed. No implementation.
- Building — implementation in progress against this page.
- Built — implemented, tested, and the page is checked against the code.
A page that drifts from the code is a bug of the same severity as a failing test. Once there is code, the merge gate will typecheck the examples on these pages against it — a documented API that does not compile is a broken build, not a stale doc.
Where to start
Getting started builds a two-device todo app with an AdonisJS backend and a React frontend. Everything else assumes it.
Basics
The everyday surface. Read in order; each assumes the one before it.
| Page | |
|---|---|
| Collections | Schema, field types, the one declaration both sides read |
| Writing data | Transactions, the outbox, and every way a write can be refused |
| Conflicts | Per-field detection, resolvers, and what merged means |
Concepts
The two things worth understanding before you design around them.
| Page | |
|---|---|
| Partitions | The consistency boundary of the whole system |
| The replica | The broker, store identity, leadership, recovery |
Digging deeper
| Page | |
|---|---|
| Offline and durability | What survives a reload, a crash and a full disk |
| Partial sync | Subsets, eviction, and when not to use them |
Reference
| Page | |
|---|---|
@locel/core | defineCollection, field types, magic columns |
@locel/client | createReplica, stores, reads, the replica API |
@locel/tanstack | locelCollectionOptions |
@locel/server | The authority, the Store port, stores |
@locel/adonisjs | Provider, config, routes, ace commands |
| Wire protocol | locel-v1 — endpoints, frames, versioning |
| Error codes | Every code, its condition and its recovery |
Every page above is Documented. Nothing is built. The decisions behind them are recorded in fourteen ADRs; implementation follows these pages, and a page moves to Building when work starts on it.
Packages
locel is split the way the AdonisJS ecosystem splits: a framework-agnostic core that holds all the logic, and integrations that hold almost none.
| Package | What it is |
|---|---|
@locel/core | Schema, wire protocol, merge engine. No dependencies, no framework, no environment assumptions. Imported by the browser and the server from the same file. |
@locel/client | The local replica — durable storage, the outbox, rebase, row reads and change notifications, and the broker that owns them. |
@locel/tanstack | Binds a replica to TanStack DB collections. |
@locel/server | The authority: sequence number assignment, per-field merge, partitions, the change stream. Stores are drivers — borrow your database through Knex or Kysely, or let locel own one. |
@locel/adonisjs | Provider, defineConfig, routes, ace commands. Wraps @locel/server; contains no sync logic. |
Design decisions
CONTEXT.md is the vocabulary. Every word in these pages that
has a narrow meaning has it there, and the API uses the same words.
.docs/adr/ records the decisions that are
expensive to reverse — fourteen of them, each with the incident behind it.
.docs/research/ records the sessions those
decisions came out of.
The ones that explain most of what these pages describe:
| 0001 | The partition is the consistency boundary |
| 0002 | Per-field versions, with writer identity |
| 0007 | The replica is one store with one transaction boundary |
| 0008 | Store identity is a fingerprint, and a mismatch refuses |
| 0012 | TanStack DB is the query layer; locel keeps optimism and durability |
| 0013 | Two store adapters over query builders; everything else is a preset |