Bloc + Feature-First + Supabase — The Complete Flutter Guide

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.

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

Also read Supabase + Riverpod for backend-focused detail.

Generate Bloc + Feature-First + Supabase on /create.

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, …
  }
}