Flutter Development Patterns

You ask the AI for a Riverpod provider, it gives you StateNotifierProvider with the legacy syntax, your codebase uses the code-generation @riverpod annotation, and now build_runner is throwing conflicting-generated-file errors. Or the AI writes a widget that rebuilds the entire tree on every keystroke and the list janks on a mid-range Android. Flutter’s problem is rarely “can the AI write Dart” - it is that Dart has three valid ways to do everything, and the AI keeps mixing them.

This recipe shows the Flutter workflows that produce code matching your existing architecture, across Cursor, Claude Code, and Codex.

What You’ll Walk Away With

• A scaffolding prompt that pins your state, routing, and networking choices so the AI stops mixing patterns
• A copy-paste prompt for a code-generation Riverpod (@riverpod) async provider that handles caching and refresh
• A go_router prompt with an auth redirect that does not loop
• A Dio API-service prompt with interceptors, retry, and typed models
• A “When This Breaks” map of the failures that actually cost time: build_runner drift, Gradle/CocoaPods, and golden-test flakiness

Scaffolding a Flutter App

Flutter’s defaults change between major versions, so state the stack explicitly. As of June 2026 the current major line is Riverpod 3.x with the code-generation @riverpod syntax, go_router for navigation, and dio for networking.

Cursor

Open Cursor in an empty folder, enter Agent mode (Cmd/Ctrl + I), and paste:

Scaffold a new Flutter app with flutter create. Set up Material 3, Riverpod 3.x using the code-generation @riverpod syntax (add riverpod_annotation, riverpod_generator, build_runner), go_router for navigation, dio for networking, and freezed for data classes. Use a feature-first folder layout (lib/features/<feature>/{data,domain,presentation}). Generate the build.yaml and a melos-free single-package setup.

Agent mode runs flutter create, edits pubspec.yaml, and runs dart run build_runner build. Review the dependency versions it pins.

Claude Code

From an empty directory:

claude "Scaffold a Flutter app with Material 3, Riverpod 3.x (code-generation \
@riverpod syntax), go_router, dio, and freezed. Use a feature-first folder \
layout and run build_runner once to verify codegen."

Then keep the session warm: claude "now add a typed AppConfig from --dart-define-from-file with a dev and prod flavor".

Codex

Codex CLI prompts are positional. From an empty directory:

codex "Scaffold a Flutter app with Material 3, Riverpod 3.x using the \
code-generation @riverpod syntax, go_router, dio, and freezed. Feature-first \
folder layout. Run build_runner to verify generated files compile."

For the longer codegen-and-verify loop, codex --full-auto lets it run build_runner and flutter analyze without prompting on each command, or hand it to Codex Cloud to scaffold and open a PR.

Caution

The most common AI mismatch in Flutter is Riverpod syntax. Riverpod 3.x favors the code-generation @riverpod annotation (part 'foo.g.dart';), but the AI’s training data is full of the legacy StateNotifierProvider / StateProvider style. Mixing them in one file produces build_runner errors that look cryptic. Always state which you use: “code-generation @riverpod syntax, not the legacy provider classes.” Paste one existing provider as a style anchor.

State with Code-Generation Riverpod

The payoff of the @riverpod annotation is that async loading, caching, and family parameters become declarative. Ask for that explicitly.

Tip

Copy-paste prompt for a code-generation Riverpod async provider:

Using Riverpod 3.x code-generation syntax, create an async provider userProfile(String userId) that fetches a profile from our ApiService (injected via another @riverpod provider). Use @Riverpod(keepAlive: true) so it caches, expose a ref.invalidate refresh, and return a freezed Profile model. Handle the loading and error states in a ConsumerWidget with ref.watch(...).when(data:, loading:, error:). Include the part 'user_profile.g.dart'; directive and the exact build_runner command to generate it.

How to evaluate the output: it must include the part '*.g.dart'; directive and use the unified Ref (Riverpod 3.x dropped the per-provider generated refs like UserProfileRef), not the old AutoDisposeFutureProviderRef. If you see StateNotifier anywhere, it reverted to the legacy style - send it back. Run dart run build_runner build --delete-conflicting-outputs and confirm it compiles before trusting it.

Navigation with go_router

The go_router auth redirect is the classic infinite-loop bug: redirect unauthenticated users to /login, but forget to allow /login itself through the guard, and the router bounces forever.

Tip

Copy-paste prompt for a go_router auth redirect that does not loop:

Set up go_router for this app with a redirect driven by an auth @riverpod provider exposed through refreshListenable. Send unauthenticated users to /login, but return null (no redirect) when they are already on /login or /register so it cannot loop. Send authenticated users away from /login to /home. Use StatefulShellRoute.indexedStack for a bottom-nav shell with three branches that preserve their own navigation stacks. Show the full GoRouter definition and how it is provided.

Check that the redirect returns null for the auth routes themselves - that single guard clause is what prevents the loop, and it is the line the AI most often omits.

Networking with Dio

Tip

Copy-paste prompt for a Dio API service with interceptors and retry:

Create an ApiService wrapping dio for this app. Add an InterceptorsWrapper that injects a bearer token from flutter_secure_storage, a retry interceptor (exponential backoff, max 3 attempts, only on 5xx and timeouts), and a LogInterceptor enabled only in debug. On 401, call a token-refresh callback once and replay the request. Return typed freezed models and surface a sealed ApiFailure (network, unauthorized, server, unknown) instead of throwing raw DioException. Show how this ApiService is exposed as a @riverpod provider.

Evaluate it on error handling: the happy path is trivial, but the 401-refresh-and-replay and the typed ApiFailure are what make it production code. If the AI just rethrows DioException, push back with “map every DioException to the sealed ApiFailure.”

Clean Architecture

For larger apps, the layering prompt is worth getting right once. Give the AI a concrete feature, not an abstract “set up clean architecture.”

Tip

Copy-paste prompt for a feature slice in clean architecture:

Generate a checkout feature in feature-first clean architecture: domain (a CartItem entity, a PlaceOrder use case returning Either<Failure, OrderId>), data (an OrderRepository interface in domain + OrderRepositoryImpl in data calling ApiService), and presentation (a @riverpod checkoutController and a CheckoutPage). Wire dependencies through Riverpod providers - no get_it. Keep the domain layer free of Flutter and dio imports. Show the folder tree and each file’s responsibility in one sentence.

The constraint that matters: the domain layer must not import Flutter or dio. Ask the AI to confirm that, then spot-check the imports - a leaked package:flutter/material.dart in a use case is the tell that the layering is cosmetic.

Testing

Tip

Copy-paste prompt for widget and golden tests:

Write widget tests for CheckoutPage using flutter_test and a ProviderScope with overridden providers (a fake OrderRepository). Cover: loading state shows a spinner, success shows the order id, failure shows the ApiFailure message, and the place-order button is disabled while submitting. Add one golden test with flutter test --update-goldens instructions and a note to run goldens on a single host OS in CI to avoid font-rendering diffs.

When This Breaks

The failure modes below are where Flutter + AI most often goes sideways:

• build_runner drift. Symptoms: “conflicting outputs,” stale generated code, or a provider that “does not exist.” Fix: dart run build_runner build --delete-conflicting-outputs, and if it still fights you, flutter clean then regenerate. Paste the exact build_runner error into the AI and ask it to identify whether the cause is a missing part directive, a legacy/codegen syntax mix, or a version mismatch between riverpod_annotation and riverpod_generator.
• Gradle and CocoaPods failures. Android build failures after a dependency bump are usually a Gradle/AGP or Kotlin version mismatch; iOS failures are usually a Pod that needs pod repo update or a higher iOS deployment target. Paste the full build log and ask the AI to pin the specific versions - do not let it bump the Flutter SDK to “fix” a Pod issue.
• Golden-test flakiness in CI. Goldens rendered on macOS locally will not match a Linux CI runner pixel-for-pixel because of font rendering. Generate and verify goldens on one OS, or load a bundled test font. If goldens flake, ask the AI to add flutter_test_config.dart that loads a fixed font before tests run.

Note

For CI itself, connect the official GitHub MCP server (https://api.githubcopilot.com/mcp/) - the same endpoint, configured per tool: a github entry with that url in .cursor/mcp.json for Cursor, claude mcp add --transport http github https://api.githubcopilot.com/mcp/ for Claude Code, and a [mcp_servers.github] block in ~/.codex/config.toml for Codex. With it connected, the agent reads your real workflows and secret names before writing the flutter test + integration_test job, instead of inventing secret names you then have to fix. For crash triage in production, the hosted Sentry MCP server (https://mcp.sentry.dev/mcp) lets the agent pull the actual stack trace and breadcrumbs for a release; a one-off skill cannot give it that live, queryable access to your issues.

What’s Next

• Expo Development Patterns if you are comparing cross-platform stacks
• React Native patterns for the JS-side comparison
• Backend integration for the API your ApiService talks to