Production-ready Flutter apps in one command.
fluFrame is a Flutter boilerplate + CLI: fluframe create my_app scaffolds a
feature-first Flutter application with state management, routing, theming,
localization, networking, flavors, strict lints, and tests — already wired
together and passing.
dart pub global activate fluframe
fluframe create my_app --org com.mycompany --backend supabase
cd my_app
flutter run --dart-define-from-file=env/dev.json
fluframe upgrade # later: pull template improvements into your appPost-1.0 stability promises are documented in docs/versioning.md.
Or use this repository as a GitHub template and start from
template/ directly.
| Concern | Solution |
|---|---|
| State management | flutter_riverpod 3 — manual Notifier/AsyncNotifier, no provider codegen |
| Navigation | go_router 17 — StatefulShellRoute bottom tabs, nested routes |
| Auth | Backend-neutral scaffold: login/profile flow, gated routes, persisted session — swap in Supabase or Firebase via one provider |
| Models | freezed 3 + json_serializable, sample REST feature |
| Networking | dio with DioException → sealed ApiException mapping |
| Persistence | KeyValueStore interface over SharedPreferencesAsync — trivially fakeable in tests |
| Localization | flutter gen-l10n (English + Korean included), no synthetic packages |
| Theming | Material 3 light/dark from one seed color, persisted ThemeMode |
| Flavors | --dart-define-from-file with env/dev.json / env/prod.json |
| Lints | very_good_analysis — zero warnings |
| Tests | Unit + widget tests with mocktail and Riverpod overrides — all green out of the box |
├── template/ # The boilerplate app (fluframe_app) — always compiles, always tested
└── packages/
└── fluframe/ # The CLI published to pub.dev (fluframe create)
The CLI runs flutter create --empty on your Flutter SDK first — platform
folders always match your installed Flutter version — then overlays the
template's lib/, test/, and configuration, rewriting package-name tokens.
The template follows a pragmatic feature-first layout:
lib/
├── main.dart # Bootstrap: load persisted settings before runApp
├── app/ # MaterialApp.router, GoRouter, themes
├── core/ # config, network, storage, logging, shared widgets
├── features/
│ ├── home/ # Counter demo — sync Notifier
│ ├── posts/ # REST list/detail demo — AsyncNotifier + FutureProvider.family
│ └── settings/ # Theme + language, persisted via KeyValueStore
└── l10n/ # ARB sources + generated localizations
Each feature keeps data/ (repositories), domain/ (models), and
presentation/ (controllers + screens) side by side. Screens read
AsyncValues through a shared AsyncValueWidget with loading/error/retry
handling built in.
Real apps generated with fluframe create and extended by the book:
examples/todo_app— persisted todo list added as a new feature module + tab (freezed, KeyValueStore, AsyncNotifier, l10n, tests)examples/weather_app— current weather from a keyless public API (Open-Meteo): absolute-URL dio calls, FutureProvider.family, city picker
# Template app
cd template
flutter pub get && flutter gen-l10n
flutter analyze && flutter test
# CLI
cd packages/fluframe
dart pub get
dart analyze && dart test -x e2e # unit tests
dart test -t e2e # full end-to-end (generates a real app)Contributions are welcome — see CONTRIBUTING.md. Please open an issue before large changes.