Cursor Rules .mdc
Production-Ready Rule • lib/**/*.dart, test/**/*.dart

Flutter 3.x & Dart Clean Architecture .cursorrules (.mdc)

Production-tested .cursorrules and .cursor/rules/*.mdc configuration for Flutter and Dart 3. Enforce clean architecture, Riverpod/Bloc state management, const widget optimization, and null safety.

.cursor/rules/flutter-dart.mdc
⚡ Open in Generator
---
description: Flutter 3 and Dart 3 production architecture, Riverpod state, and widget optimization
globs: lib/**/*.dart, test/**/*.dart
alwaysApply: false
---

# Flutter & Dart Engineering Standards

## Widget Tree & Performance Discipline
- Prefer dedicated StatelessWidget or HookWidget classes over inline helper methods that return Widget.
- Add `const` constructors to all static widgets to eliminate unnecessary element rebuilds.
- Never perform heavy data manipulation or network I/O directly inside the build() method.
- Always dispose AnimationControllers, TextEditingControllers, and StreamSubscriptions in dispose().

## State Management (Riverpod / Bloc)
- Keep UI completely decoupled from business logic using Riverpod (NotifierProvider) or Bloc.
- State models MUST be immutable using Freezed or Equatable with copyWith() patterns.
- Never call setState() in deeply nested widget trees; consume granular providers with ConsumerWidget.

## Dart Sound Null Safety & Async
- Sound null safety is strictly enforced. Never use force-unwrap (!) unless preceded by a hard null assertion.
- Handle asynchronous errors with typed Result/Either monads or structured try-catch with specific exceptions.
⭐ Using this rule in your open-source project? Reference in your README: https://cursor.pacebowl.com/rules/flutter-dart

Frequently Asked Questions & Implementation Notes

Why does this rule forbid helper methods returning Widget?

Helper methods like Widget _buildHeader() break Flutter element caching and force the entire tree to rebuild. Extracting separate const StatelessWidget classes allows Flutter to short-circuit rebuild cycles.

How does it structure Riverpod and Bloc state?

It mandates immutable state objects (using Freezed or copyWith), forbids mutable properties in state classes, and enforces separation between data layers, controllers, and UI presentation.

PaceBowl Suite Matrix

Mothership Hub →
DS
DeepSeek Studio

277+ AI Expert Prompts & R1 CoT.

CF
ComfyUI Prompt Studio

Flux.1 & 1MP Empty Latent calculator.

GEO
OpenGEO Attribution

Track Perplexity & ChatGPT conversions.