Flutter Std Tools

When to use

• Use when the user is working on Flutter/Dart features, running the app, hot reload/restart, or debugging UI.
• Use when requests mention Riverpod, Freezed, GoRouter, or Flutter widget structure.

Instructions

1. Setup: Ensure the project root is added via dart___add_roots. List devices with dart___list_devices before launching.
2. Run & lifecycle: Use dart___launch_app to run on a device. Use dart___hot_reload for UI changes (preserves state) and dart___hot_restart for logic/state resets. Avoid flutter run via shell. Stop apps with dart___stop_app.
3. Debug & inspect: Connect DTD with dart___connect_dart_tooling_daemon when needed. Use dart___get_widget_tree, dart___get_runtime_errors, and dart___get_app_logs.
4. Testing & maintenance: Run tests with dart___run_tests. Manage deps via dart___pub. Analyze/fix with dart___analyze_files and dart___dart_fix.
5. Code generation: dart run build_runner build --delete-conflicting-outputs (one-time) or dart run build_runner watch --delete-conflicting-outputs (watch).

Requirements

Architecture & tech stack

1. State Management: Must use Riverpod with code generation (@riverpod).
2. Data Models: Must use Freezed for immutable data classes and unions.
3. Dependency Injection: Must use GetIt and Injectable for service location.
4. Routing: Must use GoRouter for navigation (declarative routing).
5. Database: Must use SQLite for structured data storage.
6. Widget State Structure (Stateful/Stateless): Follow the Widget State Structure section below and split widget classes into UI, Actions, and Utils extensions.

Project Structure

• core/ - Core services and singletons
  • config/ - App configuration
  • di/ - Dependency injection setup (GetIt/Injectable)
  • routing/ - GoRouter configuration
  • utils/ - General utilities
• data/ - Data models and storage
  • consts/ - Constant definitions
  • models/ - Freezed data models
  • providers/ - Riverpod providers (using code generation)
  • repos/ - Data access layer
  • services/ - External services (API, Database, etc.)
• views/ - UI components and pages
  • pages/ - Main pages
  • widgets/ - Reusable widgets
  • pops/ - Popups and dialogs
• app.dart - App entry point widget
• main.dart - Main entry file

Additional guidelines

• Formatting: Do NOT run dart format. Follow the project's existing code style.
• Deprecations: Replace all Color.withOpacity usage with Color.withValues (Flutter 3.27+).
• Testing: utils classes require unit test coverage.

Widget State Structure (Stateful/Stateless)

To maintain clean and manageable code, split widget classes into three parts using extensions within the same file. This applies to both StatefulWidget (State class) and StatelessWidget (the widget class), separating UI from logic and event handling.

Structure

1. UI: The main State class containing the build() method and widget definitions.
2. Actions: An extension on the State class for event handlers (e.g., _onTap, _submit).
3. Utils: An extension on the State class for private helper methods and business logic.

Example (StatefulWidget)

import 'package:flutter/material.dart';

class MyPage extends StatefulWidget {
  const MyPage({super.key});

  @override
  State<MyPage> createState() => _MyPageState();
}

// 1. UI - Main State Class
class _MyPageState extends State<MyPage> {
  final _controller = TextEditingController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('My Page')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          children: [
            TextField(
              controller: _controller,
              decoration: const InputDecoration(labelText: 'Enter text'),
            ),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _onSubmit, // Reference to Actions extension
              child: const Text('Submit'),
            ),
          ],
        ),
      ),
    );
  }
}

// 2. Actions - Event Handlers
extension _MyPageActions on _MyPageState {
  void _onSubmit() {
    final text = _controller.text;
    if (_validateInput(text)) { // Reference to Utils extension
      _showSuccessDialog(text);
    } else {
      _showErrorSnackBar();
    }
  }

  void _showSuccessDialog(String text) {
    showDialog(
      context: context,
      builder: (_) => AlertDialog(
        title: const Text('Success'),
        content: Text('You entered: $text'),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('OK'),
          ),
        ],
      ),
    );
  }
}

// 3. Utils - Helper Methods & Logic
extension _MyPageUtils on _MyPageState {
  bool _validateInput(String text) {
    return text.isNotEmpty && text.length > 3;
  }

  void _showErrorSnackBar() {
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('Input must be at least 4 characters')),
    );
  }
}

Example (StatelessWidget)

import 'package:flutter/material.dart';

class MyStatelessPage extends StatelessWidget {
  const MyStatelessPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('My Stateless Page')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => _onSubmit(context), // Reference to Actions extension
          child: const Text('Submit'),
        ),
      ),
    );
  }
}

// 2. Actions - Event Handlers
extension _MyStatelessPageActions on MyStatelessPage {
  void _onSubmit(BuildContext context) {
    if (_validateInput('ok')) { // Reference to Utils extension
      _showSuccessDialog(context);
    } else {
      _showErrorSnackBar(context);
    }
  }

  void _showSuccessDialog(BuildContext context) {
    showDialog(
      context: context,
      builder: (_) => AlertDialog(
        title: const Text('Success'),
        content: const Text('Submitted.'),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('OK'),
          ),
        ],
      ),
    );
  }
}

// 3. Utils - Helper Methods & Logic
extension _MyStatelessPageUtils on MyStatelessPage {
  bool _validateInput(String text) {
    return text.isNotEmpty;
  }

  void _showErrorSnackBar(BuildContext context) {
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('Invalid input')),
    );
  }
}

Example prompts

• "Run the flutter app on the iOS simulator"
• "Hot reload the app to show the new colors"
• "Create a new Riverpod provider for user authentication using code gen"
• "Implement a settings page using the project's existing preferences store"
• "Add a SQLite table for storing todo items"
• "Add a new route for the profile page using GoRouter"
• "Fix analysis errors in the project"
• "Generate a Freezed model for User with name and age fields"