# Quickstart: browser

[`barrel-lite`](/docs/concepts/glossary#barrel-lite) is a TypeScript
client that keeps a copy of a Barrel database in the browser. Reads and
writes are local, so the app answers at once and keeps working offline;
sync sends local writes to a `barrel_server` and brings back the changes
made by other copies. In this quickstart you build a small notes app that
runs on two devices, a laptop and a phone: you give the browser a scoped
token, write a note, sync it to the second device, then edit it on both
at once and resolve the conflict. Use this path when a web app must keep
working without a network.

<Goal items={["Build barrel-lite and add it to a web app", "Give the browser a token limited to one space", "Write and read documents locally", "Sync two copies through barrel_server", "Resolve a conflict between two edits"]} />

## Before you start

- A `barrel_server` you can reach. See [Quickstart:
  server](/docs/start/quickstart-server).
- Node.js 20 or later and npm.

## 1. Get barrel-lite

You build the client from the Barrel source because `barrel-lite` 0.1.0
is not on npm. Build it from the umbrella and install
it into your app from that directory:

```shell
cd barrel/clients/barrel-lite
npm ci
npm run build
cd /path/to/your-app
npm install /path/to/barrel/clients/barrel-lite
```

## 2. Let the browser in

A web page runs on its own origin and anyone can read its code, so the
server must allow cross-origin requests (CORS) and the page must carry a
token that grants as little as possible. Add CORS and a global admin
token to the server's `sys.config` and restart it:

sys.config:

```erlang
[{barrel_server, [
    {http_port, 8080},
    {cors, #{origins => '*',
             expose => [<<"x-barrel-hlc">>]}},
    {auth, #{tokens => [<<"global-token">>]}}]}].
```

Never put the global token in a web page: it opens every database.
Instead, create a [space](/docs/concepts/glossary#space), a database
created through Barrel's agent layer that you can share, and issue a
[capability token](/docs/concepts/glossary#capability-token) for it. A
capability token grants named rights on one space only, and you can
revoke it. The space id is the database name the browser uses:

```shell
curl -X POST localhost:8080/spaces \
  -H 'authorization: Bearer global-token' \
  -H 'content-type: application/json' -d '{"label":"app"}'
curl -X POST localhost:8080/spaces/sp_7uitvqeved3z7seu/grants \
  -H 'authorization: Bearer global-token' \
  -H 'content-type: application/json' \
  -d '{"rights":["read","write"]}'
```

Output from a run on barrel_server 1.13.0:

```
{"ok":true,"space":"sp_7uitvqeved3z7seu"}
{"token":
  "bsp_alrw6fxiqga5r47x_odwpp27li6m754pfsuhbwd2n2vxek3ox44hj3zxv",
 "grant":{"rights":["read","write"],
          "space":"sp_7uitvqeved3z7seu", ...}}
```

> **Note:** The first call created the space `sp_7uitvqeved3z7seu`. The second issued
> a `bsp_...` token with `read` and `write` on that space and nothing else.
> The token is shown once, since the server stores only a hash of it; copy
> it now. `read` covers pulls, `write` covers pushes.

## 3. Open, write, read

`Database.open` creates the local copy and remembers which server
database it syncs with. You then write and read as if the database were
local, because it is.

```ts

const remote = {
  url: "http://localhost:8080",
  db: "sp_7uitvqeved3z7seu",
  token: "bsp_alrw6fxiqga5r47x_...",
};
const laptop = await Database.open("notes", { remote });

await laptop.put({ id: "n1", title: "hello" });
await laptop.get("n1");
```

Output from a run of barrel-lite 0.1.0 in Node 22:

```
{"id":"n1",
 "version":"000001a1ba4159ea00000000@wd31d29e133c6788f"}
{"title":"hello","id":"n1"}
```

> **Note:** `put` answered with the document id and its `version`, the
> [revision](/docs/concepts/glossary#revision) token of this write, the
> same token the server calls `_rev`. `get` read the note back from the
> local store. Nothing has reached the server yet.

Writes go to the local store at once. In a browser the store is OPFS;
where OPFS is missing (Node, for example) it is in memory.

## 4. Sync

Sync is how copies catch up with each other. A push sends local writes to
the server, a pull applies the changes the server has from other copies,
and `sync()` does both.

```ts
await laptop.sync();             // push, then pull
const live = laptop.liveSync();  // keep syncing
live.stop();
```

Open a second copy the same way, on another device or in another
browser. Its first sync brings the document in, and local BQL reads it:

```ts
const phone = await Database.open("notes", { remote });
await phone.sync();
await phone.get("n1");
await phone.query(
  "SELECT id, title FROM db WHERE title = 'hello'");
```

Output from a run of barrel-lite 0.1.0 in Node 22 against barrel_server 1.13.0:

```
{"push":{"pushed":1,"skipped":0,"conflicts":0},
 "pull":{"scanned":1,"applied":0}}
{"push":{"pushed":0,"skipped":0,"conflicts":0},
 "pull":{"scanned":1,"applied":1}}
{"id":"n1","title":"hello"}
[{"id":"n1","title":"hello"}]
```

> **Note:** The first line is the laptop's `sync()`: its push sent one document
> (`pushed: 1`), and its pull saw one change on the server, its own, so
> there was nothing to apply. The second line is the phone's: it had
> nothing to push and applied one change, the note. The phone then reads
> the note locally, by id and with BQL.

## 5. Resolve a conflict

Offline copies can change the same note at the same time. Barrel does not
drop either edit: both versions are kept, every copy picks the same
winner, and the other version is kept as a
[conflict](/docs/concepts/glossary#conflict) for you to resolve. Edit
the note on both copies before they sync, then sync:

```ts
await laptop.put({ id: "n1", title: "hello from the laptop" });
await phone.put({ id: "n1", title: "hello from the phone" });
await laptop.sync(); await phone.sync(); await laptop.sync();

await laptop.get("n1");
await phone.get("n1");
await laptop.conflicts("n1");
```

Output from a run of barrel-lite 0.1.0 in Node 22 against barrel_server 1.13.0:

```
{"id":"n1","title":"hello from the phone"}
{"id":"n1","title":"hello from the phone"}
[{"version":"000001a1ba415a1600000001@wd31d29e133c6788f",
  "deleted":false,
  "body":{"id":"n1","title":"hello from the laptop"}}]
```

> **Note:** Both copies show the phone's edit: the winner is the version with the
> highest token, so every copy reaches the same answer without talking to
> each other. This is [convergence](/docs/concepts/glossary#convergence).
> The laptop's edit is not lost: `conflicts` returns it with its version
> and body.

`resolve` replaces the winner and every conflict with one body. Push it,
and the other copy gets the resolution on its next pull:

```ts
await laptop.resolve("n1", { title: "hello from both" });
await laptop.push();
await phone.pull();
await phone.get("n1");
await phone.conflicts("n1");
```

Output from a run of barrel-lite 0.1.0 in Node 22 against barrel_server 1.13.0:

```
{"id":"n1","title":"hello from both"}
[]
```

> **Note:** The phone now reads the resolved body, and its conflict list is empty:
> the resolution replaced both versions on every copy that pulled it.

`put` on a document in conflict replaces only the winner; the conflicts
stay. Pass `null` to `resolve` to resolve to a delete.

## Notes

> **Limit:** The local store is a cache. Writes not yet flushed are lost on a crash,
> and the browser may evict the whole store. The server copy is the source
> of truth, so sync often.

- Vector, keyword and hybrid search (`vector_top_k`, `bm25_top_k`,
  `hybrid_top_k`) and `SUBSCRIBE` run on the server only; use
  `db.queryRemote`. Locally they throw `BqlServerOnlyError`.
- barrel-lite authenticates with bearer tokens only, global or
  capability. It does not sign requests.
- With `multiTab: true` one tab syncs and the others go through it.
- The full client is described in [barrel-lite](/docs/guides/barrel-lite).

<NextSteps steps={[
  { href: '/docs/guides/barrel-lite', label: 'barrel-lite', why: 'Read the full client: storage, live sync, attachments and multiple tabs.' },
  { href: '/docs/concepts/versions', label: 'Versions, conflicts, convergence', why: 'Understand how every copy picks the same winner.' },
  { href: '/docs/concepts/spaces', label: 'Spaces and capabilities', why: 'Scope and revoke the tokens you hand to browsers and agents.' },
]} />
