# Flutter Isar > Implement local data persistence with Isar database and offline-first architecture. Use when building cache-first data strategies, reactive queries, schema migrations, or secure local storage with flutter_secure_storage. Use when this capability is needed. - Skill: `tomevault-io/flutter-isar` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/flutter-isar` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/flutter-isar/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/flutter-isar --- # Isar Database - Use **Isar** as the primary local database for structured data persistence - Define collections using `@collection` annotation with `Id` field - Place collection definitions in the `data/local/` directory of the relevant feature - Run `dart run build_runner build --delete-conflicting-outputs` after modifying collections ## Schema Design - Keep collections focused — one collection per domain entity - Use `@Index` annotations for fields queried frequently - Use `@enumerated` for enum fields - Use `Links` and `Backlinks` for relationships between collections - NEVER store derived/computed values — compute them in the domain layer ## Migrations - Isar handles additive schema changes automatically (new fields, new collections) - For breaking changes (renamed fields, removed fields), write migration logic in the repository - Version your database schema and check version on app startup # Repository Pattern for Local Data - Local DataSource wraps all Isar `put`, `get`, `delete`, `watch` calls - Repositories orchestrate between remote and local DataSources - Repositories decide cache-first vs network-first strategy per use case # Offline-First Patterns - **Cache-First**: Read from Isar first, fetch from network in background, update Isar on success - **Network-First**: Fetch from network, fall back to Isar on failure - **Write-Behind**: Write to Isar immediately, sync to server asynchronously (queue pending changes) - Always show cached data immediately while refreshing in background # Reactive Queries - Use Isar's `watchLazy()` or `watch()` to stream changes to the UI via BLoC - Wrap Isar watch streams in the repository and expose as `Stream>` - Dispose stream subscriptions properly in BLoC `close()` method # Secure Storage - Use `flutter_secure_storage` for sensitive key-value data (tokens, encryption keys) - Use `SharedPreferences` ONLY for non-sensitive user preferences (theme, locale, onboarding flags) - NEVER store passwords, tokens, or secrets in `SharedPreferences` or plain Isar --- > Source: [dhruvanbhalara/skills](https://github.com/dhruvanbhalara/skills) — distributed by [TomeVault](https://tomevault.io).