Flutter App Expert Rules

tl;dr: pull flutter-app-expert-cursorrules-prompt-file.mdc from awesome-cursorrules before any Flutter project in Cursor. Models default to Provider + raw setState and skip the layered core/features/{data,domain,presentation} split.

What it does

This rule set configures Cursor to write Flutter 3.x apps with Material 3, a feature-first clean-architecture layout, BLoC for state, GoRouter for navigation, and GetIt for dependency injection. Without it, models drift toward setState plus provider and pile business logic into widget files.

Sourced from PatrickJS/awesome-cursorrules — the community registry for .mdc Project Rules.

The rules

// Flutter App Expert .cursorrules

// Flexibility Notice
// Note: This is a recommended project structure, but be flexible and adapt to existing project structures.
// Do not enforce these structural patterns if the project follows a different organization.
// Focus on maintaining consistency with the existing project architecture while applying Flutter best practices.

// Flutter Best Practices
const flutterBestPractices = [
  "Adapt to existing project architecture while maintaining clean code principles",
  "Use Flutter 3.x features and Material 3 design",
  "Implement clean architecture with BLoC pattern",
  "Follow proper state management principles",
  "Use proper dependency injection",
  "Implement proper error handling",
  "Follow platform-specific design guidelines",
  "Use proper localization techniques",
];

// Project Structure (reference; adapt to existing project organization)
const projectStructure = `
lib/
  core/
    constants/
    theme/
    utils/
    widgets/
  features/
    feature_name/
      data/      (datasources, models, repositories)
      domain/    (entities, repositories, usecases)
      presentation/ (bloc, pages, widgets)
  l10n/
  main.dart
test/
  unit/
  widget/
  integration/
`;

// Coding Guidelines
1. Use proper null safety practices
2. Implement proper error handling with Either type
3. Follow proper naming conventions
4. Use proper widget composition
5. Implement proper routing using GoRouter
6. Use proper form validation
7. Follow proper state management with BLoC
8. Implement proper dependency injection using GetIt
9. Use proper asset management
10. Follow proper testing practices

// Widget Guidelines
1. Keep widgets small and focused
2. Use const constructors when possible
3. Implement proper widget keys
4. Follow proper layout principles
5. Use proper widget lifecycle methods
6. Implement proper error boundaries
7. Use proper performance optimization techniques
8. Follow proper accessibility guidelines

// Performance Guidelines
1. Use proper image caching
2. Implement proper list view optimization
3. Use proper build methods optimization
4. Follow proper state management patterns
5. Implement proper memory management
6. Use proper platform channels when needed
7. Follow proper compilation optimization techniques

// Testing Guidelines
1. Write unit tests for business logic
2. Implement widget tests for UI components
3. Use integration tests for feature testing
4. Implement proper mocking strategies
5. Use proper test coverage tools
6. Follow proper test naming conventions
7. Implement proper CI/CD testing

Installation

Drop the .mdc into .cursor/rules/ of your Flutter project:

mkdir -p .cursor/rules
curl -sL \
  https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/flutter-app-expert-cursorrules-prompt-file.mdc \
  -o .cursor/rules/flutter-app-expert.mdc

Cursor picks up files in .cursor/rules/ automatically.

Suggested layout

lib/
  core/
    constants/
    theme/
    utils/
    widgets/
  features/
    <feature>/
      data/      (datasources, models, repositories)
      domain/    (entities, repositories, usecases)
      presentation/ (bloc, pages, widgets)
  l10n/
  main.dart

Pair with:

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_bloc: ^8.1.0
  go_router: ^14.0.0
  get_it: ^7.6.0
  dartz: ^0.10.1   # Either
  equatable: ^2.0.5

Why it helps

Without Flutter-aware rules, models will:

• Use setState or Provider instead of flutter_bloc, mixing local and global state
• Inline business logic inside build() methods and inflate widget files
• Skip the data/domain/presentation split, putting API calls next to widgets
• Pick Navigator.push over GoRouter, breaking deep links and web URL sync
• Forget to mark services with Either<Failure, T> returns, leaking exceptions into the UI

These rules keep each feature scannable and testable without locking you to the structure if your project already differs.

Gotchas

• The file’s header note explicitly says: “be flexible and adapt to existing project structures. Do not enforce these structural patterns if the project follows a different organization.” If your repo is feature-first vs. layer-first, follow what is there.
• These are Cursor .mdc rules, not a Claude Code CLAUDE.md file. For Claude Code, paraphrase into your project’s CLAUDE.md.
• Either here refers to dartz (or fpdart). If your project uses result_dart, the pattern still applies but the import differs.
• The performance section says “use proper platform channels when needed” — only do that when no Dart-side plugin exists. Don’t write platform channels for things like shared_preferences or path_provider.

Related

• React Router v7 Rules — same “URL-first state” idea, applied to Flutter’s GoRouter
• TanStack Query v5 Rules — analogous server-state separation, for React/TS projects