Adding Civility to an app #
Guides for adding Civility to an app — a reactive local data layer whose contents live on the user's devices and, when they choose, sync through a Civility server (yours, theirs, or a hosted one).
These guides assume an app built the Inro way — a static PWA scaffolded with inro init, routed with @inro/ui, precached by @inro/workers (see inro/docs/apps/). Civility is what you add when that app needs data: a store, binary blobs, cross-device sync, share links, or AI services. Applications may encrypt their own data before storing it. Start with local state, add the rest as you need them.
Protocol-level design lives in the specs under docs/spec/; per-symbol API docs are generated at https://jsr.io/@civility/<package>/doc.
The app store convention #
www/store/app.ts owns your state and fans changes out to the UI. Routes come and go; the store outlives them, so components import the singleton and subscribe to it.
// www/store/app.ts
import { Store } from '@civility/store'
import { IDBStorage } from '@civility/store/idb'
const APP_ID = 'me.example.myapp'
const store = new Store({
storage: { db: new IDBStorage({ id: APP_ID }) },
documents: ['settings'],
collections: ['items'],
versions: [{
version: globalThis.__INRO__?.version ?? '0.0.0',
schema: appSchema,
}],
})
export class App {
settings = store.document<Settings>('settings', { theme: 'auto' })
items = store.collection<Item>('items')
#subs = new Set<() => void>()
constructor() {
store.subscribe(() => this.#notify())
this.#init()
}
async #init() {
await this.settings.preload()
await this.items.preload()
this.#notify()
}
#notify() {
for (const cb of this.#subs) cb()
}
addEventListener(fn: () => void) {
this.#subs.add(fn)
}
removeEventListener(fn: () => void) {
this.#subs.delete(fn)
}
}
export default new App()
The store turns every change — local or pulled from sync — into one "something changed" signal. globalThis.__INRO__.version is injected by inro build, so your schema version tracks releases automatically. Routes subscribe in connectedCallback and re-render on change — see Store for Document / Collection / Property and schema migrations.
Swapping Store for @civility/cloud's CloudStore is what turns local state into synced state — same API, plus cloud.share and cross-app replicas. See Sync.
Features #
| Guide | Package | What it gives you |
|---|---|---|
| Store | @civility/cloud |
Reactive local state and optional content-addressed blobs — with schema migrations. |
| Sync | @civility/cloud |
Push/pull stored data and blobs to a Civility server across devices. |
| Services | @civility/services |
Call AI and other credentialed services — bring-your-own-key or host bundle. |
store and local blobs work on their own; sync adds cross-device replication. The civ-* UI for sync settings, share dialogs, and usage meters is @civility/ui (spec §18), which drops into Inro layouts and cascade layers unchanged.
Shipping an app with sync also involves:
- Registration — app id, manifest, and origin verification for the consent popup.
- Testing — in-memory model tests and integration tests against a real server.
(App-shell concerns — routing, service workers, deployment — are Inro's: see inro/docs/apps/.)
Recipes #
Complete shapes for common apps, each built from the features above:
- Todo list — a single
Collection, the "hello world" of the store. - Journal — dated entries plus a settings document.
- Gallery — images with
@civility/store/blobs, synced lazily. - AI-powered — structured generation with
@civility/services. - Public share links — publish a document as a read-only link with
@civility/cloud.