mobiai-flutter

name	mobiai-flutter
description	Use when working on a Flutter or Dart project — building, testing, debugging, understanding state management and project structure.
license	MIT
compatibility	["claude-code","cursor","copilot","codex"]
platforms	["flutter"]

Flutter / Dart

Community contribution welcome! Help flesh out this skill with Flutter patterns, state management approaches, and real-world workflows.

Guide for working with Flutter projects.

When to Use

• Working on a Flutter/Dart project
• Debugging widget issues, state management problems, or platform channel errors
• Writing tests for Flutter code

Detecting a Flutter Project

# Check for Flutter indicators
ls pubspec.yaml lib/ test/ 2>/dev/null
cat pubspec.yaml | head -20
flutter --version

Project Structure

project/
  lib/
    main.dart                     # Entry point
    app.dart                      # App widget
    features/
      home/
        home_screen.dart          # Screen widget
        home_bloc.dart            # State management (BLoC example)
        home_state.dart
        home_event.dart
        widgets/                  # Feature-specific widgets
    core/
      models/                     # Data models
      services/                   # API, database
      utils/                      # Helpers
  test/
    features/
      home/
        home_bloc_test.dart
    widget_test.dart
  pubspec.yaml                    # Dependencies
  analysis_options.yaml           # Lint rules

Build Commands

# Run in debug mode
flutter run

# Build debug APK
flutter build apk --debug

# Build release APK
flutter build apk --release

# Build iOS
flutter build ios --release

# Run analysis (lint)
flutter analyze

# Format code
dart format lib/

State Management Detection

# BLoC
grep -r "flutter_bloc\|BlocProvider\|BlocBuilder" lib/ --include="*.dart" | head -5

# Riverpod
grep -r "flutter_riverpod\|ProviderScope\|ConsumerWidget" lib/ --include="*.dart" | head -5

# Provider
grep -r "^import.*provider" lib/ --include="*.dart" | head -5

# GetX
grep -r "get:\|GetMaterialApp\|GetxController" lib/ --include="*.dart" | head -5

# MobX
grep -r "flutter_mobx\|Observable\|@action" lib/ --include="*.dart" | head -5

Testing

Unit Tests

// test/features/home/home_bloc_test.dart
import 'package:test/test.dart';

void main() {
  group('HomeBloc', () {
    late HomeBloc bloc;

    setUp(() {
      bloc = HomeBloc(repository: MockRepository());
    });

    test('initial state is HomeInitial', () {
      expect(bloc.state, isA<HomeInitial>());
    });

    test('emits [Loading, Loaded] when data fetch succeeds', () {
      expectLater(
        bloc.stream,
        emitsInOrder([isA<HomeLoading>(), isA<HomeLoaded>()]),
      );
      bloc.add(LoadHomeData());
    });
  });
}

Widget Tests

testWidgets('displays loading indicator', (tester) async {
  await tester.pumpWidget(
    MaterialApp(home: HomeScreen()),
  );
  expect(find.byType(CircularProgressIndicator), findsOneWidget);
});

Run Tests

# All tests
flutter test

# Specific file
flutter test test/features/home/home_bloc_test.dart

# With coverage
flutter test --coverage

Common Issues

• Widget rebuild performance: Check for unnecessary rebuilds with const constructors
• State management leaks: Ensure BLoC/controllers are properly disposed
• Platform channel errors: Check both Dart and native (Android/iOS) code
• Hot reload doesn't work: Try hot restart (R in terminal) or full restart

Tracing Bugs

1. Check the error in the console — Flutter errors are usually descriptive
2. Widget tree issues: Use Flutter Inspector or debugDumpApp()
3. State management: Add logging to state transitions
4. Platform channel: Check both sides (Dart + native)

---

Want to improve this skill? Share your Flutter expertise, architecture patterns, and debugging techniques via a PR.