1# Getting started with a generated lofi app23This guide begins after installing [Deno 2.9 or newer](https://docs.deno.com/runtime/).45## Create and run the app67```sh8deno run -A jsr:@nzip/lofi/create my-app9cd my-app10deno task dev11```1213Open the URL printed by Astro. The starter contains a task list, an account panel when sync is14available, and device/runtime diagnostics. A hosted instance of this same starter, restyled, runs at15[demo.lofi.host](https://demo.lofi.host); it is generated and deployed from each release tag.1617Verify the local-first baseline before changing anything:1819```mermaid20flowchart LR21 A["Add a task"] --> B["Reload"]22 B --> C{"Task remains?"}23 C -- "yes" --> D["Disconnect network"]24 D --> E["Add or complete a task"]25 E --> F{"UI still works?"}26 C -- "no" --> G["Run doctor"]27 F -- "no" --> G28 F -- "yes" --> H["Local-first baseline verified"]29```3031The default app is local-only. It does not require an `.env`, an account ceremony, or a backend.3233## Run the project checks3435```sh36deno task doctor37deno task test38deno task build39deno task preview40```4142`doctor` checks the project layout, configuration, manifest, and referenced install assets without43printing values. `test` runs the fast, deterministic suite. `build` creates the production PWA in44`dist/`, then verifies its base-aware HTML links, manifest, worker, build identity, and precache as45one artifact. `preview` serves that exact output at `http://127.0.0.1:4321/` by default.4647## Know which files to change4849| File or directory | Purpose |50| -------------------- | ----------------------------------------------------------- |51| `src/schema.ts` | Tables and typed fields |52| `src/permissions.ts` | Read and mutation policies |53| `src/app.ts` | App name, database name, stable origins, and repository URL |54| `src/pages/` | Astro pages and shell composition |55| `src/islands/` | Preact hooks and interactive UI |56| `src/styles/` | Application styling |57| `public/` | Manifest, icon, and other product assets |58| `tests/` | Application and local-first browser tests |5960Application hooks import supported runtime seams from `@nzip/lofi`, as the generated `use-tasks.ts`61does. The boundary keeps Jazz networking and storage machinery out of product components while62allowing framework fixes to arrive through a package upgrade.6364The final package map is intentionally small:6566| Import | Supported use |67| -------------------------------------------- | --------------------------------------------------- |68| `@nzip/lofi` | App configuration, runtime, session, stores, PWA |69| `@nzip/lofi/access` | Private, direct-share, and fixed-role group helpers |70| `@nzip/lofi/preact` | Package-owned Preact hooks and diagnostic UI |71| `@nzip/lofi/astro` | Package-owned Astro/Vite integration |72| `@nzip/lofi/recipes/file-handler` | Optional validated installed-app file import drafts |73| `@nzip/lofi/recipes/launch-handler` | Optional safe installed-window launch routing |74| `@nzip/lofi/recipes/protocol-handler` | Optional allow-listed custom-protocol item links |75| `@nzip/lofi/recipes/related-app-discovery` | Optional presentation-only companion discovery |76| `@nzip/lofi/recipes/scope-extension` | Optional reciprocal cross-origin app-window scope |77| `@nzip/lofi/recipes/web-share` | Optional inbound/outbound text and link sharing |78| `@nzip/lofi/recipes/window-controls-overlay` | Optional desktop titlebar geometry observation |79| `@nzip/lofi/testing` | Local-first Playwright helpers |80| `@nzip/lofi/{create,dev,...}` | Generator and generated-project command entrypoints |8182All of these imports resolve through the single version pinned in `deno.json`. Upgrade that pin to83receive framework fixes; do not copy package files into `src/` or import unpublished internal paths.84Direct vendor access is an unsupported escape hatch: isolate it from ordinary product files and do85not expect lofi compatibility guarantees for it.8687## Customize the application identity first8889Before accumulating local data, update `src/app.ts`:9091- `name` is the human-facing application name.92- `databaseName` namespaces durable browser storage.93- `repositoryUrl` controls the starter footer link.94- `credentialOrigins` lists hostnames you intend to keep stable if you use device credentials.9596Also update `public/manifest.webmanifest`, `public/favicon.svg`, the page title, and starter copy.9798Changing `databaseName` later points the browser at a different local database. Choose it early so a99cosmetic rename does not make existing device data appear to disappear.100101## Replace the task example102103The fastest path is to change one layer at a time while keeping the app runnable:104105```mermaid106flowchart LR107 A["Edit schema"] --> B["Update permissions"]108 B --> C["Create domain hook"]109 C --> D["Build the island UI"]110 D --> E["Update tests"]111 E --> F["doctor → test → build"]112```113114Continue with [Data and UI](data-and-ui.md) for the table-to-island pattern and115[Permissions](permissions.md) before exposing new data.116117## Add sync only when you need it118119Local-only development is the normal starting point. To add managed Jazz sync and account recovery:120121```sh122deno task jazz:provision123```124125Then follow [Sync and recovery](sync-and-recovery.md). Provisioning makes sync available; each user126still chooses whether their existing local account should begin syncing.