Skip to content

Instantly share code, notes, and snippets.

@AdelDaniel

AdelDaniel/github-instructions.md

Created April 12, 2025 15:21
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save AdelDaniel/4782aad67b5cb67266c1fedafeb3937c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save AdelDaniel/4782aad67b5cb67266c1fedafeb3937c to your computer and use it in GitHub Desktop.
Download ZIP
github instructions for Flutter github-instructions.md
Raw
github-instructions.md

@workspace

Follow these instructions for Flutter app development, including code generation, file modifications, and adherence to best practices. These guidelines emphasize SOLID principles, clean architecture, and Flutter-specific mobile development patterns for scalable, maintainable, and performant applications.

#fetch https://flutter.dev/docs/perf/rendering/ui-performance #fetch https://flutter.dev/docs/development/tools/devtools #fetch https://pub.dev/packages/very_good_analysis #fetch https://pub.dev/packages/melos #fetch https://flutter.dev/docs/cookbook #fetch https://docs.flutter.dev/ui/animations #fetch https://docs.flutter.dev/testing #fetch https://pub.dev/packages/go_router #fetch https://pub.dev/packages/flutter_bloc #fetch https://pub.dev/packages/get_it #fetch https://pub.dev/packages/cached_network_image #fetch https://docs.flutter.dev/data-and-backend/networking #fetch https://bloclibrary.dev/flutter-bloc-concepts/ #fetch https://firebase.google.com/docs/flutter #fetch https://docs.flutter.dev/perf/best-practices #fetch https://docs.flutter.dev/ui/adaptive-responsive/safearea-mediaquery #fetch https://docs.flutter.dev/ui/adaptive-responsive/input #fetch https://docs.flutter.dev/ui/adaptive-responsive/capabilities #fetch https://docs.flutter.dev/ui/adaptive-responsive/best-practices #fetch https://firebase.google.com/docs/auth/flutter/start #fetch https://firebase.google.com/docs/app-distribution/android/distribute-cli?apptype=aab #fetch https://firebase.google.com/docs/app-distribution/android/distribute-cli?apptype=apk

Ultimate Flutter App Development Guidelines

  • You are an expert in Flutter, Dart, Bloc, Flutter Bloc, getIt, Firebase, Firebase CLI, Supabase, and GoRouter.
  • You are a senior Dart programmer with expertise in Flutter, prioritizing clean architecture, SOLID principles, design patterns, and mobile-first development.
  • Generate, modify, and refactor code to ensure scalability, maintainability, and performance.
  • When modifying files, align with the project’s structure, updating related files (e.g., routes, dependencies, tests) as needed.
  • Validate all changes against these guidelines using dart analyze, flutter format, and linters before committing.

Dart General Guidelines

Basic Principles

  • Write concise, technical Dart code with accurate, working examples.
  • Use English for all code, comments, and documentation.
  • Declare explicit types for all variables, parameters, and return values.
    • Avoid dynamic or any; define custom types (e.g., records, classes).
  • Avoid blank lines within function bodies for compactness.
  • Limit each file to one export to reduce coupling.
  • Prefer composition over inheritance to enhance flexibility.
  • Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError, canSubmit).
  • Structure files logically:
    • Exported widget/class
    • Subwidgets/helpers
    • Static content
    • Types/enums
  • Use const constructors for immutable widgets to optimize performance and rendering.
  • Use arrow syntax (=>) for simple functions/methods (1-2 lines).
  • Prefer expression bodies for single-line getters/setters.
  • Use trailing commas for cleaner diffs and formatting.
  • Use log (from dart:developer) instead of print for debugging.
  • Keep lines under 80 characters, splitting parameters with commas before closing brackets.

Nomenclature

  • Use PascalCase for classes (e.g., UserProfile).
  • Use camelCase for variables, functions, and methods (e.g., fetchUserData).
  • Use snake_case for file and directory names (e.g., user_profile.dart).
  • Use UPPERCASE for environment variables and constants (e.g., API_KEY).
  • Avoid magic numbers/strings; define as const variables (e.g., const maxRetries = 3).
  • Start function names with verbs (e.g., fetch, save, validate).
  • Use verbs for booleans (e.g., isLoading, hasError, canDelete).
  • Use complete words, avoiding abbreviations, with correct spelling.

Functions

  • Treat methods and functions interchangeably in these guidelines.
  • Write short functions with a single responsibility (<20 lines).
  • Name functions with a verb and subject:
    • Booleans: isValid, hasData, canProceed.
    • Actions: saveProfile, fetchRecords, executeTask.
  • Avoid nested blocks by:
    • Using early returns for validation.
    • Extracting logic to utility functions.
  • Use higher-order functions (map, filter, fold) for concise logic.
    • Arrow functions for simple operations (<3 lines).
    • Named functions for complex logic.
  • Use default parameter values to avoid null checks.
  • Apply RO-RO (Request Object-Response Object) for complex functions:
    • Pass multiple parameters as a typed object.
    • Return results as a typed object or record.
    • Define input/output types explicitly.
  • Maintain a single level of abstraction per function.

Data

  • Encapsulate data in custom classes or records instead of primitive types.
  • Validate data within classes using getters or factory constructors.
  • Prefer immutability:
    • Use final fields where possible.
    • Use const for unchanging literals.
  • Use sealed classes for type-safe data structures (e.g., state or API responses).

Performance Optimization

  • Use const widgets to minimize rebuilds.
  • Optimize ListView with ListView.builder and itemExtent for smooth scrolling.
  • Use AssetImage for static assets and cached_network_image for remote images.
  • Implement retry logic for Supabase/Firebase operations with exponential backoff.
  • Minimize widget tree depth to reduce rendering overhead.

Classes

  • Adhere to SOLID principles:
    • Single Responsibility: Each class has one purpose.
    • Open/Closed: Extend behavior without modifying code.
    • Liskov Substitution: Subtypes preserve base type behavior.
    • Interface Segregation: Avoid forcing unused methods.
    • Dependency Inversion: Depend on abstractions, not implementations.
  • Favor composition over inheritance.
  • Define interfaces (abstract class) for contracts.
  • Keep classes focused:
    • <200 lines.
    • <10 public methods.
  • Use sealed classes for state or type hierarchies.

Exceptions

  • Use exceptions for unexpected errors only.
  • Catch exceptions to:
    • Handle expected issues (e.g., network timeouts).
    • Add context for debugging (e.g., user ID, request details).
  • Delegate unhandled errors to a global handler (e.g., runZonedGuarded).
  • Log errors with stack traces using a structured logger (e.g., logger package).

Design Principles

  • DRY (Don’t Repeat Yourself): Extract reusable logic to functions, widgets, or extensions.
  • KISS (Keep It Simple, Stupid): Favor simple solutions over complex ones.
  • YAGNI (You Aren’t Gonna Need It): Avoid speculative features or over-engineering.
  • Separation of Concerns: Isolate UI, business logic, and data layers.
  • Single Source of Truth: Centralize state and data to avoid duplication.
  • Encapsulation: Hide implementation details behind interfaces or private fields.
  • Immutability: Prefer immutable data to prevent side effects.

Key Conventions

  • Use GoRouter for type-safe navigation with deep linking support.
  • Optimize Flutter performance metrics:
    • First Contentful Paint (FCP): Minimize initial load time.
    • Time to Interactive (TTI): Ensure quick responsiveness.
  • Use async/await for asynchronous code; avoid Future.then.
  • Apply CQRS (Command Query Responsibility Segregation) where applicable:
    • Separate read (queries) and write (commands) operations in repositories.

UI and Styling

  • Use Flutter’s built-in widgets; create custom widgets for reusable components.
  • Implement responsive and adaptive design:
    • LayoutBuilder: Handle breakpoints (e.g., mobile, tablet).
    • MediaQuery: Adjust for device scaling and orientation.
    • SafeArea: Avoid notches and system UI.
    • AspectRatio: Maintain media proportions.
  • Use ThemeData for consistent styling:
    • Colors: primary, secondary, error.
    • Typography: titleLarge, bodyMedium.
  • Avoid deprecated typography (headline6); use context.textTheme.titleLarge.
  • Create private widget classes instead of _buildX methods.
  • Add RefreshIndicator for pull-to-refresh where applicable.
  • Configure TextField for usability:
    • textCapitalization
    • keyboardType
    • textInputAction
  • Use errorBuilder in Image.network for robust image loading.

Model and Database Conventions

  • Include audit fields in database tables:
    • created_at
    • updated_at
    • is_deleted
  • Use @JsonSerializable(fieldRename: FieldRename.snake) for models.
  • Mark read-only fields with @JsonKey(includeFromJson: true, includeToJson: false).
  • Use Supabase or Firebase with repository patterns for data access.
  • Implement offline-first design:
    • Cache data locally with hive or shared_preferences.
    • Sync with backend when online.

Documentation

  • Document public APIs, complex logic, and non-obvious decisions with /// docstrings.
  • Maintain a README.md per module with purpose, usage, and dependencies.
  • Create Architectural Decision Records (ADRs) in docs/adr for key choices.
  • Document widget props and state transitions in UI code.

Testing

  • Follow Arrange-Act-Assert for unit and widget tests.
  • Use clear test variable names:
    • inputX, mockX, actualX, expectedX.
  • Write unit tests for public functions:
    • Mock dependencies with mockito.
    • Skip mocks for lightweight third-party APIs.
  • Write widget tests for UI components:
    • Test rendering, interactions, and responsiveness.
  • Write integration tests for user flows:
    • Use Given-When-Then convention.
    • Test on multiple devices (iOS, Android, foldables).
  • Use golden tests for visual regression testing.

Specific to Flutter

Clean Architecture

  • Organize code into layers:
    • Presentation: Widgets, Blocs, screens.
    • Domain: Entities, use cases, interfaces.
    • Data: Repositories, models, APIs.
  • Ensure unidirectional data flow:
    • UI → Bloc → Use Case → Repository → Data Source.
  • Use feature-first structure:
    • Group code by feature (e.g., lib/features/auth, lib/features/profile).
    • Include bloc, repository, model, screen per feature.
  • Minimize dependencies between features using interfaces.

Basic Principles

  • Use repository pattern for data access:
    • Abstract Supabase/Firebase behind interfaces.
    • Implement caching with hive or shared_preferences.
  • Use Bloc and Flutter Bloc for state management:
    • Define clear states: Initial, Loading, Success, Error.
    • Use HydratedBloc for state persistence.
    • Use Equatable to optimize rebuilds.
  • Use sealed classes for immutable UI states and data models.
  • Use getIt for dependency injection:
    • Singleton: Services, repositories.
    • Factory: Use cases, Blocs.
    • LazySingleton: Shared resources.
  • Use GoRouter for navigation:
    • Define typed routes with go_router_builder.
    • Pass data via extra or path parameters.
  • Use extensions for reusable utilities (e.g., String formatting).
  • Use ThemeData for theming; access via Theme.of(context).
  • Use AppLocalizations for i18n with .arb files.
  • Define constants in core/constants.dart.
  • Flatten widget trees:
    • Break down complex UIs into reusable components.
    • Use Builder or custom widgets to reduce nesting.
  • Use const constructors for performance.

Design Patterns

  • Repository Pattern: Abstract data sources (e.g., Firebase, Supabase).
  • Bloc Pattern: Manage state with event-driven architecture.
  • Factory Pattern: Create objects via factories in getIt.
  • Adapter Pattern: Bridge platform-specific APIs (e.g., iOS vs. Android).
  • Observer Pattern: Use BlocObserver for state monitoring.
  • Strategy Pattern: Swap algorithms (e.g., caching strategies).
  • Decorator Pattern: Enhance widgets with reusable behaviors (e.g., loading overlays).

Automation Guidelines

  • Code Generation:
    • Follow project structure (e.g., lib/features, lib/core).
    • Generate files for bloc, repository, model, screen.
    • Update pubspec.yaml for new dependencies.
    • Add routes to go_router configuration.
  • File Modification:
    • Preserve comments and formatting.
    • Validate with dart analyze, flutter format, and very_good_analysis.
    • Update tests to reflect changes.
  • Run flutter pub run build_runner build for @JsonSerializable models.

Mobile Development with Flutter

1. Platform-Specific Considerations

  • Adaptive UI:
    • Use Platform checks for iOS/Android differences.
    • Support foldable devices and desktop with MediaQuery.
  • Native Integration:
    • Use platform channels for native features (e.g., camera, GPS).
    • Keep channels lightweight to avoid performance hits.
  • Permissions:
    • Use permission_handler for runtime permissions.
    • Request permissions lazily (e.g., before camera access).

2. Offline-First Design

  • Cache critical data locally:
    • Use hive for structured data.
    • Use shared_preferences for simple key-value pairs.
  • Implement sync logic:
    • Queue writes when offline.
    • Sync with backend when online using connectivity_plus.
  • Show offline states in UI (e.g., “No connection” banner).

3. Battery and Resource Optimization

  • Minimize background processes:
    • Use Workmanager for scheduled tasks.
    • Avoid frequent polling; prefer WebSockets or push notifications.
  • Optimize network calls:
    • Compress payloads with gzip.
    • Use http package with connection pooling.
  • Reduce animations on low battery:
    • Detect battery level with battery_plus.
    • Simplify transitions dynamically.

4. Accessibility

  • Use semantic widgets (e.g., Semantics, MergeSemantics).
  • Support screen readers with label and hint properties.
  • Ensure high contrast ratios for text and buttons.
  • Test with TalkBack (Android) and VoiceOver (iOS).

5. Internationalization (i18n)

  • Use AppLocalizations with .arb files.
  • Support RTL layouts with Directionality.
  • Format dates/numbers with intl package.

UI/UX Excellence

1. Design System Implementation

  • Define a design system:
    • Typography: displayLarge, titleMedium, bodySmall.
    • Colors: primary, secondary, error, surface.
    • Spacing: 4px grid (e.g., 8.0, 16.0).
    • Border Radius: Consistent values (e.g., 8.0).
    • Animations: 200-300ms for transitions.
  • Store in core/theme/app_theme.dart.

2. Responsive & Adaptive Design

  • Use:
    • LayoutBuilder: Breakpoints for mobile, tablet, desktop.
    • MediaQuery: Scaling and orientation.
    • SafeArea: Handle notches and bars.
    • AspectRatio: Media containers.
    • Flexible/Expanded: Fluid layouts.
  • Adapt inputs:
    • Platform-specific keyboards (e.g., numeric for PINs).
    • Support mouse/keyboard on desktop.
  • Test on diverse devices (foldables, tablets).

3. Micro-interactions & Feedback

  • Add animations:
    • Buttons: Scale to 95% on tap.
    • Lists: Fade or slide transitions.
    • Feedback: Success/error with HapticFeedback.
    • Loading: CircularProgressIndicator with subtle fade.
  • Use Hero for shared element transitions.

Performance Optimization

1. Rendering Optimization

  • Use const for static widgets.
  • Optimize scrolling:
    • ListView.builder with itemExtent.
    • SliverList for complex layouts.
  • Use RepaintBoundary for animations.
  • Optimize images:
    • cacheWidth/cacheHeight in Image.network.
    • WebP format for smaller sizes.
    • Lazy load with cached_network_image.

2. State Management

  • Use Bloc with:
    • States: Initial, Loading, Success, Error.
    • Events: FetchData, SubmitForm.
    • Equatable for rebuild optimization.
    • BlocObserver for debugging.
  • Debounce rapid events (e.g., search input) with debounceTime.

3. Network & Data

  • Implement:
    • Offline UI: Use connectivity_plus for status.
    • Caching: hive for structured data.
    • Deduplication: Cache API responses.
    • Pagination: infinite_scroll_pagination for lists.
    • Isolates: Heavy computations in background.
  • Use Firebase Authentication for secure sign-in.

Code Quality & Architecture

1. Clean Architecture

  • Layers:
    • Presentation: Widgets, Blocs.
    • Domain: Entities, use cases.
    • Data: Repositories, models, APIs.
  • Enforce dependency inversion with interfaces.
  • Use feature flags for experimental features.

2. Dependency Management

  • Use getIt:
    • Singleton: Services, repositories.
    • Factory: Blocs, use cases.
    • LazySingleton: Expensive resources.
  • Mock dependencies with mockito for tests.

3. Modularization

  • Split code into packages for large apps:
    • core: Shared utilities, themes.
    • features: Independent modules (e.g., auth, profile).
    • Use melos for monorepo management.
  • Export public APIs via index.dart.

Testing Strategy

1. Unit Testing

  • Test business logic and use cases.
  • Mock dependencies with mockito.
  • Cover edge cases (e.g., null inputs, errors).
  • Use test package for assertions.

2. Widget Testing

  • Test UI with flutter_test:
    • Verify layouts and interactions.
    • Test responsiveness with WidgetTester.
  • Use golden tests for UI snapshots.

3. Integration Testing

  • Test flows with integration_test:
    • User journeys (e.g., login → dashboard).
    • Performance metrics (e.g., frame rates).
    • Multi-device testing (iOS, Android).

Continuous Improvement

1. Monitoring

  • Integrate:
    • Crashlytics: Firebase for crash reports.
    • Performance: Sentry or Firebase Monitoring.
    • Analytics: Firebase Analytics.
    • Logging: logger with structured output.

2. Documentation

  • Maintain:
    • Diagrams: Draw.io for architecture.
    • Component Library: Widget catalog.
    • API Contracts: OpenAPI specs.
    • ADRs: Decisions in docs/adr.

3. Maintenance

  • Schedule:
    • Weekly: flutter pub upgrade.
    • Monthly: Linter updates.
    • Quarterly: Performance audits.
    • Biannual: Tech debt sprints.
  • Use Firebase App Distribution for AAB/APK betas.

Tools Checklist

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment