name: flutter-state description: Flutter state management skill hub: async/loading/error models, caching/invalidation, and patterns for Riverpod and BLoC (including testing).

Skill: State Management (Shared, Riverpod, BLoC)

Purpose

This hub routes state management topics: how to model state, handle async/loading/error, implement caching/invalidation, and choose patterns for Riverpod or BLoC.

When to use

• UI has inconsistent loading/error behavior.
• Business rules leak into widgets.
• Multiple features need shared caching or invalidation.
• You are deciding between Riverpod/BLoC or improving an existing setup.

When NOT to use

• If the issue is pure Dart logic, start with dart/SKILL.md.
• If the issue is networking/storage boundaries, start with data/SKILL.md.

Core concepts

• Single source of truth: one owner for state.
• Immutable state: predictable transitions.
• Events vs commands: choose a model that matches your domain.
• Async state: represent loading, data, error, and retry explicitly.

Recommended patterns

• Keep UI state near UI, domain state near domain.
• Use typed failures and explicit retry paths.
• Cache with explicit invalidation rules; avoid hidden global caches.

Minimal example

Where to go next:

- Modeling state -> shared/state_modeling.md
- Loading/error/retry -> shared/async_state.md
- Caching/invalidation -> shared/caching_state.md
- Testing state -> shared/testing_state.md
- Riverpod patterns -> riverpod/*
- BLoC patterns -> bloc/*

Edge cases

• Async flows that outlive the screen must be cancelled or ignored.
• Multiple listeners can trigger duplicate loads; coordinate.

Common mistakes

• Mixing domain logic into widget trees.
• Modeling errors as strings instead of typed failures.

Testing strategy

• Unit tests for state transitions.
• Widget tests for wiring.
• Integration tests for critical flows.

Related skills

• Error modeling
• Repository pattern
• Testing hub