123# @nzip/lofi45**Build installable Deno web apps that open immediately, keep working offline, and sync when users6choose.**78lofi generates an [Astro](https://astro.build) + [Preact](https://preactjs.com) app backed by9durable local data. Users start with a private, on-device account—no sign-in or network required—and10can add [Jazz](https://jazz.tools)-powered sync and recovery later without replacing that identity11or rewriting product code.1213[Documentation](https://lofi.host/docs) · [API reference](https://lofi.host/api) ·14[Live demo](https://demo.lofi.host) · [JSR package](https://jsr.io/@nzip/lofi) ·15[MIT License](LICENSE)1617Building with an AI agent? Feed it [llms.txt](https://lofi.host/llms.txt) for an index of the18documentation, or [llms-full.txt](https://lofi.host/llms-full.txt) for the complete docs and API19reference in one file — both generated from the deployed version's sources.2021## Quick start2223Requires **Deno 2.9+**. It is the only global runtime you need.2425```sh26deno run -A jsr:@nzip/lofi/create my-app27cd my-app28deno task dev29```3031Open the URL printed by the development server. The starter is a small task app: add a task and32reload the page to see that it remains in durable local storage. Once the page is open, disconnect33the network and you can keep reading and writing data locally. Prefer to look first? A reworked34build of the starter runs at [demo.lofi.host](https://demo.lofi.host), deployed by the release35workflow from the published package.3637The generated app starts in local-only mode. You do not need an account, a backend, or an `.env`38file to begin building. To provision managed Jazz sync, scaffold with `--sync` or run39`deno task jazz:provision` later; either way users keep the account they already have.4041Continue with [Getting started](https://lofi.host/docs/getting-started) when you are ready to42replace the task example with your own schema, permissions, hook, and UI.4344## What you get4546- **Local-first data** read from durable local storage; failures are surfaced, never silently47 swapped for memory.48- **Identity from the first launch**, with optional sync and account recovery via passkey or a49 24-word phrase.50- **Narrow collaboration templates** — private, direct-share, and fixed-role group access behind a51 small [`@nzip/lofi/access`](https://lofi.host/api/access) API.52- **Verbs with sync-boundary effects** — `s.mutation` declares named verbs whose writes return a53 `WriteHandle`; `onSynced`/`onRejected` consequences run on the originating device from a durable54 journal that survives reloads, with pending-write and per-row sync status hooks for the UI.55- **A schema compatibility gate** — each build stamps the schema range it understands, so a stale56 offline shell that meets newer data pauses editing (reads continue), shows the update path, and57 coordinates the worker swap across tabs.58- **Local-first test helpers** — Playwright-backed two-client fixtures for offline writes and59 convergence.60- **An explicit authoring boundary**: product code owns schema, permissions, config, islands,61 styles, and tests; lofi owns storage, identity, sync, lifecycle, and PWA plumbing.6263The [documentation](https://lofi.host/docs) covers all of this in depth: guides,64[commands](https://lofi.host/docs/reference/commands),65[project layout](https://lofi.host/docs/reference/project-layout),66[installed-app recipes](https://lofi.host/docs/recipes),67[examples](https://lofi.host/docs/examples/shared), and the68[identity and recovery model](https://lofi.host/docs/auth-identity).6970## Where lofi fits7172lofi is designed for mobile web apps where offline operation is a requirement, not a best-effort73enhancement. Keep these current constraints in mind:7475- lofi is an early, pre-1.0 release; do not yet trust it with data you cannot afford to lose.76- The data layer is Jazz 2 alpha and deliberately pinned to a reviewed version77 ([stack and version policy](https://lofi.host/#stack)). Five known engine defects at the current78 pin are each documented in a decision record and covered by an automated canary that fails loudly79 when a version bump changes the behavior.80- The sync server reads unencrypted columns. The [threat model](https://lofi.host/docs/threat-model)81 states what the server can and cannot see, what the user holds, and which fields the schema can82 seal.83- The supported browser floors are Android Chrome 148+ and iOS Safari 16.4+.84- Recovery is user-controlled: lofi does not retain recoverable account material on the server, so85 the recovery phrase must be kept safe.8687## Developing lofi itself8889This repository is the framework's development monorepo. `package/` contains the `@nzip/lofi`90source, `apps/reference/` is the reference app against which the generator is validated, and91`website/` builds the [lofi.host](https://lofi.host) documentation site.9293See [CONTRIBUTING.md](https://github.com/FelineStateMachine/lofi/blob/main/CONTRIBUTING.md) for the94repository workflow and the95[DevX contract](https://github.com/FelineStateMachine/lofi/blob/main/docs/devx-contract.md) for the96framework's testable promises and boundaries.