Flutter Enterprise Starter Kit

An open source Flutter starter kit showing how a production app is actually built: Clean Architecture, Cubit state management, dependency injection, Firebase, and a complete CI/CD pipeline, ready to build on.

Features

• Clean Architecture (data / domain / presentation) per feature
• Cubit state management (flutter_bloc)
• Dependency injection (get_it)
• Firebase Authentication: email/password sign-in, register, sign-out
• Dev/prod flavors, each with its own Firebase project
• Typed error handling (Freezed + Either, via fpdart)
• Unit & Cubit tests (mocktail, bloc_test)
• GitHub Actions CI: analyze + test on every PR
• REST API feature via Dio, with local caching (posts)
• Fastlane: build + Firebase App Distribution per flavor (Android); iOS build validation only

Tech stack

Project structure

lib/
  core/           # DI, networking, error handling, theming, routing; shared by every feature
  features/
    auth/         # Firebase email/password auth, the fullest example, read this one first
    home/         # Post-login landing page
    posts/        # REST CRUD via Dio, real Freezed+json_serializable model, Hive cache
  app.dart, bootstrap.dart, main_development.dart, main_production.dart

Every feature follows the same data -> domain -> presentation layering. See ARCHITECTURE.md for why each piece exists, a full request walkthrough, and the platform-specific gotchas (Firebase's duplicate-app conflict, macOS entitlements) hit and fixed along the way.

Getting started

flutter pub get
dart run build_runner build --delete-conflicting-outputs   # generates *.freezed.dart / *.g.dart
flutter run -t lib/main_development.dart                   # or lib/main_production.dart

The checked-in firebase_options_*.dart files point at this repo's own Firebase projects. To run against your own, create two Firebase projects with Email/Password Authentication enabled, then:

flutterfire configure --project=<your-dev-project> --out=lib/firebase_options_development.dart
flutterfire configure --project=<your-prod-project> --out=lib/firebase_options_production.dart

Run the test suite:

flutter test

Fastlane

fastlane android build_dev        # or build_prod
fastlane android distribute_dev   # builds, then uploads to Firebase App Distribution
fastlane ios build_dev            # compiles only, no signing (see ARCHITECTURE.md)

distribute_dev/distribute_prod need a FIREBASE_TOKEN environment variable (firebase login:ci generates one). The same lanes run from .github/workflows/release.yml, using a FIREBASE_TOKEN repository secret, two ways:

• dev: automatically, on every push to main. No one has to remember to ship a dev build, it's always current.
• prod: manually, from the Actions tab (workflow_dispatch, flavor choice). Production stays a deliberate human action on purpose, see "Why Firebase App Distribution" in ARCHITECTURE.md.

Roadmap

• Real Android release signing (current release builds use Flutter's default debug-signed config, fine for Firebase App Distribution, not for the Play Store)
• iOS distribution, blocked on a paid Apple Developer Program account (see ARCHITECTURE.md)
• Widget tests + coverage reporting (currently only unit/cubit tests exist; wire flutter test --coverage into CI with a coverage badge)
• Localization (flutter_localizations/intl), all user-facing strings are hardcoded today
• Push notifications via Firebase Cloud Messaging
• Analytics via Firebase Analytics
• Changelog automation from conventional commits (already used throughout this repo's history)