Claude
Skills
Sign in
Back

flutter-isar

Included with Lifetime
$97 forever

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.

General

What this skill does


# 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<List<DomainModel>>`
-   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

Related in General