Bloc + Feature-First + Supabase — The Complete Flutter Guide
Bloc for events/states, Feature-First folders, Supabase auth — what FlutterInit generates and when this stack beats Clean + Firebase.
Stack Configuration — what FlutterInit generates for this guide
When to choose this stack
Choose this when you want predictable Bloc flows, features that own their folders, and Postgres-backed auth via Supabase — without waiting to invent the wiring yourself.
Bloc + Feature-First + Supabase is the stack for teams that like explicit events and states, organize code by feature, and want Supabase instead of Firebase. FlutterInit generates lib/src/features/... with auth Bloc/Cubit-style wiring, a Supabase AuthService, and go_router — then documents it in AGENTS.md so agents keep the pattern.
What This Stack Generates
- Feature-First tree under
lib/src/features/{auth,home,onboarding} - Auth with domain repository + data impl + presentation Bloc (
auth_bloc.dart,session_bloc.dart) - Supabase init via dotenv (
SUPABASE_URL,SUPABASE_ANON_KEY) and email/password auth - go_router routes for onboarding, login, signup, forgot password, home
- AI context: AGENTS.md, CLAUDE.md, DESIGN.md, Cursor rules
Honest note: in FlutterInit today, Feature-First and Clean share the same feature folder shape. The difference is how you think about growth and what the agent docs emphasize — not a totally different physical layout.
Project Structure
Bloc in the presentation layer
Generated auth logic follows events → states. Screens dispatch login/signup; the Bloc talks to AuthRepository, which talks to Supabase through AuthService.
class AuthBloc extends Bloc<AuthEvent, AuthState> {
final AuthRepository _repository;
AuthBloc({required AuthRepository repository})
: _repository = repository,
super(const AuthState.initial()) {
on<AuthLoginRequested>(_onLogin);
// signup, forgot password, …
}
}
UI uses BlocBuilder / BlocListener — not random setState for auth.
Supabase auth wiring
AuthService uses AppConfig.supabase and signInWithPassword / signUp / onAuthStateChange, wrapped in runTask → Either. You still add your Supabase project keys in .env (see SETUP.md).
When to choose this vs alternatives
| Prefer | Instead |
|---|---|
| This stack | Predictable Bloc + Supabase + feature folders |
| Riverpod + Clean + Firebase | Firebase ecosystem + Riverpod |
| MVVM + Provider + Appwrite | Less ceremony, Appwrite |
Also read Supabase + Riverpod for backend-focused detail.
Generate Bloc + Feature-First + Supabase on /create.
Ready to build?
Generate this project in seconds
FlutterInit scaffolds the entire structure described in this guide — wired up, typed, and ready for flutter run.