TinyBase: A Super-Light Reactive Store for Local-First Apps

TinyBase is a tiny (~5–11 KB), fully-tested, open-source reactive data store with built-in indexing, metrics, schema enforcement, queries, and CRDT sync. It’s tailored for local-first apps and works anywhere JS runs—browser, Node, even workers.

1. Getting Started & Store Basics

Install or grab it via CDN.

1npm install tinybase

1import {createStore} from 'tinybase'
2const store = createStore()
3store.setValue('count', 1)
4console.log(store.getValue('count')) // → 1

You can also manage tabular data:

1store.setTable('pets', {fido: {species: 'dog'}})
2store.setCell('pets', 'fido', 'color', 'brown')
3console.log(store.getRow('pets', 'fido'))
4// → { species: 'dog', color: 'brown' }

Reactive listeners let you respond to changes at any granularity.

2. React Integration (Optional UI Layer)

Use tinybase/ui-react for seamless React binding:

1import {useCell} from 'tinybase/ui-react'
2
3function PetColor({store}) {
4  const color = useCell('pets', 'fido', 'color', store)
5  return <>Color: {color}</>
6}

The UI updates automatically when the cell changes.

3. Structuring Data: Schemas, Indexes, Relationships, Metrics

Schemas enforce types and defaults:

1store.setTablesSchema({
2  pets: { species: {type: 'string'}, sold: {type: 'boolean', default: false} }
3})

Indexes speed up lookups:

1const indexes = createIndexes(store)
2indexes.setIndexDefinition('bySpecies', 'pets', 'species')

Relationships link tables:

1const rels = createRelationships(store)
2rels.setRelationshipDefinition('petSpecies', 'pets', 'species', 'species')

Metrics allow aggregations (e.g., tracking max price):

1const metrics = createMetrics(store)
2metrics.setMetricDefinition('maxPrice', 'pets', 'max', 'price')

4. Persistence & Sync

Persistence: Persist store to sessionStorage, IndexedDB, or files:

1import {createSessionPersister} from 'tinybase/persisters/persister-browser'
2const persister = createSessionPersister(store, 'myApp')
3await persister.save()

Sync: Use CRDT-based MergeableStore for syncing across peers or server:-

• Via WebSockets (e.g., createWsServer + WsSynchronizer)
• Third-party CRDT systems (Yjs, Automerge)
• Databases (SQLite, Postgres)
• Cloudflare Durable Objects

5. Architect Your App

TinyBase gives you flexibility:

• Standalone memory-only store (good for prototypes)
• Read-only cloud-loaded data
• Local browser persistence
• Client-only sync via CRDT
• Client-server sync (server as source of truth)
• Third-party integration (Automerge, Yjs)
• Use multiple stores if needed—one for transient UI state, another for persisted documents, etc.

6. Advanced Features

Undo/Redo via Checkpoints

Query engine (TinyQL) for SQL-like reactive queries and joins

Inspector Tool for real-time debugging of your store

Summary

TinyBase is a micro-reactive data store that handles everything from simple key-value pairs to rich UI-bindings, sync, persistence, and undo. Add only what you need and architect complex local-first experiences with minimal footprints.