Connected apps with 3rd-party data hosts jsr.io/@civility
README.md

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.