flutter_provider_kit 0.0.5

A provider-based MVI architecture (MviViewModel, onAction, UiEventEmitter) and recommended folder structure, extending flutter_basic_kit_library.

flutter_provider_kit

Read this in other languages: 한국어

A flutter_basic_kit_library extension that provides a provider-based architecture separating data / domain / presentation layers, plus the reusable base classes that architecture is built on (MviViewModel, UiEventEmitter, UseCase, Result).

What's included

• Result<T> — a Success/Failure sealed class, handled with Dart 3 pattern matching (switch)
• UseCase<Output, Params> — base class the use cases under domain/use_case/ extend
• MviViewModel<S, A> — a ChangeNotifier-based class that holds state (S) and takes every user action through a single entry point, onAction(A action), dispatched with switch (State/Action-style MVI)
• UiEventEmitter<E> — a mixin for MviViewModel that emits one-off UI events (E) — snackbars, navigation — as a Stream
• Re-exports the whole provider package (no need to add provider separately)

MviViewModel doesn't force a wrapper widget on you. Screens read state the standard provider way: context.watch<MyViewModel>().state. When a screen needs to change state, it doesn't grow another public method — it calls the single onAction(Action) entry point.

Install

dependencies:
  flutter_provider_kit: ^0.0.4

⚠️ Installing is not enough — you must run init. flutter pub get only downloads this package; it does not create any folders or add the architecture libraries. pub get has no auto-run hook (unlike npm's postinstall), so scaffolding is a deliberate, one-time command (next section). Run it once and both the folder structure and the dependency stack land in your project.

Scaffold the structure — run this once (required)

init does two things in a single command: (1) generates the recommended folders plus a minimal, ready-to-run home feature, and (2) adds the architecture libraries to your pubspec.yaml.

# With the package added as a dependency:
dart run flutter_provider_kit:init          # creates presentation/home/
dart run flutter_provider_kit:init login    # feature name as an argument (presentation/login/)

# Or activate the command globally and run it from any project:
dart pub global activate flutter_provider_kit
provider_kit init

1. Folders + files it generates

• data/data_source, data/repository, domain/model, domain/repository, domain/use_case — empty layer folders
• presentation/<feature>/ — minimal state / action / ui_event / view_model / screen stubs
• di/provider_setup.dart — a manual build<Feature>ViewModel()
• core/routing/route_paths.dart + core/routing/router.dart — a go_router config routing RoutePaths.<feature> to <Feature>Screen

2. Libraries it adds — mirrored from flutter_basic_kit_library

init reads flutter_basic_kit_library's own pubspec.yaml at runtime and adds the same runtime + dev stack to your app, so the generated architecture works out of the box: routing (go_router), DI (get_it, injectable), networking (dio, retrofit), model codegen (freezed, json_serializable, build_runner), plus google_fonts, intl, flutter_secure_storage, and more. Because it reads that package directly, the list is a single source of truth — when flutter_basic_kit_library adds or bumps a library, init picks it up with no change here. provider is already bundled (re-exported) by this package, so it isn't added separately.

Existing files are never overwritten, so re-running is safe.

After running init, verify the setup once:

flutter pub get
flutter analyze
dart run build_runner build --delete-conflicting-outputs   # if you use the codegen models

Recommended folder structure

example/ implements a "photo search" feature end to end (with mock data) using this structure.

lib/
  data/
    data_source/
      photo_api.dart              # external API calls (mocked here)
    repository/
      photo_repository_impl.dart  # implements the domain's abstract interface
  domain/
    model/
      photo.dart                  # freezed model
    repository/
      photo_repository.dart       # abstract interface
    use_case/
      get_photos_use_case.dart    # extends UseCase<Output, Params>
  presentation/
    home/
      components/
        photo_widget.dart         # widget local to home
      home_screen.dart            # reads state via context.watch<HomeViewModel>(), dispatches via onAction(Action)
      home_action.dart            # every user action the screen can produce (sealed)
      home_state.dart             # the state the screen reads on every rebuild
      home_ui_event.dart          # one-off events like snackbars/navigation
      home_view_model.dart        # extends MviViewModel<HomeState, HomeAction> with UiEventEmitter<HomeUiEvent>
  di/
    provider_setup.dart           # manual wiring of repository/use_case/view_model
  main.dart
test/
  data/
    photo_api_test.dart
  ui/
    home_view_model_test.dart

Layer rules

• domain is pure business logic with no dependency on Flutter or external packages. repository/ holds only abstract interfaces; the real implementation lives in data/repository/.
• data implements domain's interfaces and isolates real API/DB calls inside data_source/.
• presentation is split into per-feature folders (home/, detail/, ...), each bundling its own state/action/view_model/screen/components.
• di is currently manual, function-based wiring (provider_setup.dart). The structure is kept swappable for get_it/injectable (already bundled via flutter_basic_kit_library) once that's needed — not decided yet.

Usage

class HomeViewModel extends MviViewModel<HomeState, HomeAction>
    with UiEventEmitter<HomeUiEvent> {
  HomeViewModel(this._getPhotosUseCase) : super(const HomeState());

  final GetPhotosUseCase _getPhotosUseCase;

  @override
  void onAction(HomeAction action) {
    switch (action) {
      case Search(:final query):
        _search(query);
    }
  }

  Future<void> _search(String query) async {
    emit(state.copyWith(isLoading: true));
    switch (await _getPhotosUseCase(query)) {
      case Success(:final data):
        emit(state.copyWith(photos: data, isLoading: false));
      case Failure(:final error):
        emit(state.copyWith(isLoading: false));
        emitEvent(ShowErrorSnackBar(error.toString()));
    }
  }
}

// screen
final state = context.watch<HomeViewModel>().state;
context.read<HomeViewModel>().onAction(const Search('flutter'));

See example/ for the full working app.

Under consideration

• A NestJS-CLI-style code generator for repository/use_case CRUD boilerplate (not started, to be discussed separately)
• Whether to move DI to get_it/injectable

Related packages

Package	Status
flutter_basic_kit_library	Published
flutter_provider_kit	this package
flutter_riverpod_kit	Published
flutter_bloc_kit	Published

Versioning

This package follows Semantic Versioning. See CHANGELOG.md for the full history.

Additional information

• Repository: https://github.com/cleanwash/flutter_provider_kit
• Issues: https://github.com/cleanwash/flutter_provider_kit/issues