lofi developer documentation

These guides are for developers building an application from the @nzip/lofi generated template. They describe the checked-out package version and its generated project—not the older prototype sketches under docs/spikes/.

Start here

Work through the guides in order; each builds on the project state the previous one leaves behind.

Step	Guide	What you do
1	Getting started	Scaffold an app, verify local persistence, and identify the files you are expected to change.
2	Data and UI	Connect a Jazz table to a typed Preact hook and island.
3	Permissions	Understand and change the starter's owner-only access policy.
4	Sync and recovery	Provision managed sync and understand the account lifecycle.
5	Testing	Run fast tests and the opt-in two-client offline convergence example.
6	Deployment	Build, preview, customize, and host the static PWA.
7	Application-origin migration	Move a deployed app across a browser security boundary with recovery, verification, rollback, and retirement.

Blocked at any step — environment, browser, build, or test failures? Go straight to Troubleshooting.

The root README provides the shortest product overview and command summary. AI agents can ingest these docs as llms.txt (index) or llms-full.txt (complete corpus including the API reference).

Reference

• Commands
• Configuration
• Generated project layout
• Identity and recovery model
• Account and access API
• Access template examples — who may touch which rows
  • Direct sharing
  • Fixed-role group
  • Policy conditions on typed columns
• Nouns and verbs — declaring verbs, effect units, and the write lifecycle
• The effect library — built-in effect units and the custom-unit authoring contract
• Data modeling examples — how to shape tables and columns
  • Collaborative list data model
  • Collaborative sets
  • Binary and structured payloads
  • Schema evolution
  • Nested app namespaces
• Store provisioning
• lofi-node — the sync node your users can run to own their data's location; tutorials, guides, and the node reference live in the site's /node section
• Optional installed-app recipes
• Advanced device-auth primitive

The author boundary

Generated projects intentionally divide application source from versioned framework code:

• Change src/schema.ts, src/permissions.ts, src/app.ts, src/pages/, src/layouts/, src/islands/, and src/styles/.
• Import documented runtime seams from @nzip/lofi; no framework implementation is copied into src/.
• Change files under public/ when customizing the icon or manifest. The package build generates the service worker.
• Keep application tests under tests/.

Framework contributor material

The following documents explain why lofi behaves as it does. They are useful when changing the framework, but they are not application tutorials:

• Developer-experience contract
• Historical prototype seed
• docs/spikes/ and retained evidence

Spike evidence records the state of an experiment at a specific commit and package pin. Preserve it as historical evidence; do not update it to look like the current generated app.