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.1516Verify the local-first baseline before changing anything:1718```mermaid19flowchart LR20 A["Add a task"] --> B["Reload"]21 B --> C{"Task remains?"}22 C -- "yes" --> D["Disconnect network"]23 D --> E["Add or complete a task"]24 E --> F{"UI still works?"}25 C -- "no" --> G["Run doctor"]26 F -- "no" --> G27 F -- "yes" --> H["Local-first baseline verified"]28```2930The default app is local-only. It does not require an `.env`, an account ceremony, or a backend.3132## Run the project checks3334```sh35deno task doctor36deno task test37deno task build38deno task preview39```4041`doctor` checks the project layout, configuration, manifest, and referenced install assets without42printing values. `test` runs the fast, deterministic suite. `build` creates the production PWA in43`dist/`, then verifies its base-aware HTML links, manifest, worker, build identity, and precache as44one artifact. `preview` serves that exact output at `http://127.0.0.1:4321/` by default.4546## Know which files to change4748| File or directory | Purpose |49| -------------------- | ----------------------------------------------------------- |50| `src/schema.ts` | Tables and typed fields |51| `src/permissions.ts` | Read and mutation policies |52| `src/app.ts` | App name, database name, stable origins, and repository URL |53| `src/pages/` | Astro pages and shell composition |54| `src/islands/` | Preact hooks and interactive UI |55| `src/styles/` | Application styling |56| `public/` | Manifest, icon, and other product assets |57| `tests/` | Application and local-first browser tests |5859Application hooks import supported runtime seams from `@nzip/lofi`, as the generated `use-tasks.ts`60does. The boundary keeps Jazz networking and storage machinery out of product components while61allowing framework fixes to arrive through a package upgrade.6263The final package map is intentionally small:6465| Import | Supported use |66| -------------------------------------------- | --------------------------------------------------- |67| `@nzip/lofi` | App configuration, runtime, session, stores, PWA |68| `@nzip/lofi/access` | Private, direct-share, and fixed-role group helpers |69| `@nzip/lofi/preact` | Package-owned Preact hooks and diagnostic UI |70| `@nzip/lofi/astro` | Package-owned Astro/Vite integration |71| `@nzip/lofi/recipes/file-handler` | Optional validated installed-app file import drafts |72| `@nzip/lofi/recipes/launch-handler` | Optional safe installed-window launch routing |73| `@nzip/lofi/recipes/protocol-handler` | Optional allow-listed custom-protocol item links |74| `@nzip/lofi/recipes/related-app-discovery` | Optional presentation-only companion discovery |75| `@nzip/lofi/recipes/scope-extension` | Optional reciprocal cross-origin app-window scope |76| `@nzip/lofi/recipes/web-share` | Optional inbound/outbound text and link sharing |77| `@nzip/lofi/recipes/window-controls-overlay` | Optional desktop titlebar geometry observation |78| `@nzip/lofi/testing` | Local-first Playwright helpers |79| `@nzip/lofi/{create,dev,...}` | Generator and generated-project command entrypoints |8081All of these imports resolve through the single version pinned in `deno.json`. Upgrade that pin to82receive framework fixes; do not copy package files into `src/` or import unpublished internal paths.83Direct vendor access is an unsupported escape hatch: isolate it from ordinary product files and do84not expect lofi compatibility guarantees for it.8586## Customize the application identity first8788Before accumulating local data, update `src/app.ts`:8990- `name` is the human-facing application name.91- `databaseName` namespaces durable browser storage.92- `repositoryUrl` controls the starter footer link.93- `credentialOrigins` lists hostnames you intend to keep stable if you use device credentials.9495Also update `public/manifest.webmanifest`, `public/favicon.svg`, the page title, and starter copy.9697Changing `databaseName` later points the browser at a different local database. Choose it early so a98cosmetic rename does not make existing device data appear to disappear.99100## Replace the task example101102The fastest path is to change one layer at a time while keeping the app runnable:103104```mermaid105flowchart LR106 A["Edit schema"] --> B["Update permissions"]107 B --> C["Create domain hook"]108 C --> D["Build the island UI"]109 D --> E["Update tests"]110 E --> F["doctor → test → build"]111```112113Continue with [Data and UI](data-and-ui.md) for the table-to-island pattern and114[Permissions](permissions.md) before exposing new data.115116## Add sync only when you need it117118Local-only development is the normal starting point. To add managed Jazz sync and account recovery:119120```sh121deno task jazz:provision122```123124Then follow [Sync and recovery](sync-and-recovery.md). Provisioning makes sync available; each user125still chooses whether their existing local account should begin syncing.