Wzorce rozwoju Flutter

Prosisz AI o provider Riverpod, dostajesz StateNotifierProvider ze starą składnią, Twoja baza kodu używa adnotacji @riverpod z generowaniem kodu, a teraz build_runner wyrzuca błędy o sprzecznych wygenerowanych plikach. Albo AI pisze widget, który przebudowuje całe drzewo przy każdym naciśnięciu klawisza, a lista zacina się na Androidzie ze średniej półki. Problem Fluttera rzadko brzmi „czy AI potrafi pisać Dart” - chodzi o to, że Dart ma trzy poprawne sposoby na zrobienie wszystkiego, a AI raz po raz je miesza.

Ten przepis pokazuje przepływy pracy z Flutter, które produkują kod pasujący do Twojej istniejącej architektury, w Cursor, Claude Code i Codex.

Co z tego wyniesiesz

• Prompt do szkieletu, który przypina Twoje wybory stanu, routingu i networkingu, żeby AI przestało mieszać wzorce
• Gotowy do wklejenia prompt na asynchroniczny provider Riverpod z generowaniem kodu (@riverpod), który obsługuje cachowanie i odświeżanie
• Prompt na go_router z przekierowaniem autoryzacji, które się nie zapętla
• Prompt na serwis API z Dio z interceptorami, ponawianiem i typowanymi modelami
• Mapę „Gdy to się sypie” z awariami, które naprawdę kosztują czas: dryf build_runner, Gradle/CocoaPods i niestabilność testów golden

Tworzenie szkieletu aplikacji Flutter

Domyślne ustawienia Fluttera zmieniają się między wersjami głównymi, więc podaj stos jawnie. Na czerwiec 2026 aktualną linią główną jest Riverpod 3.x ze składnią @riverpod z generowaniem kodu, go_router do nawigacji i dio do networkingu.

Cursor

Otwórz Cursor w pustym folderze, wejdź w tryb Agent (Cmd/Ctrl + I) i wklej:

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.

Tryb Agent uruchamia flutter create, edytuje pubspec.yaml i wykonuje dart run build_runner build. Przejrzyj wersje zależności, które przypina.

Claude Code

Z pustego katalogu:

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."

Następnie utrzymuj sesję ciepłą: claude "now add a typed AppConfig from --dart-define-from-file with a dev and prod flavor".

Codex

Prompty Codex CLI są pozycyjne. Z pustego katalogu:

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."

Przy dłuższej pętli generowania i weryfikacji codex --full-auto pozwala mu uruchamiać build_runner i flutter analyze bez pytania o każde polecenie, albo przekaż to do Codex Cloud, żeby zbudował szkielet i otworzył PR.

Uwaga

Najczęstszą rozbieżnością AI we Flutterze jest składnia Riverpod. Riverpod 3.x preferuje adnotację @riverpod z generowaniem kodu (part 'foo.g.dart';), ale dane treningowe AI są pełne starego stylu StateNotifierProvider / StateProvider. Mieszanie ich w jednym pliku produkuje błędy build_runner, które wyglądają zagadkowo. Zawsze wskazuj, którego używasz: „code-generation @riverpod syntax, not the legacy provider classes.” Wklej jeden istniejący provider jako wzorzec stylu.

Stan z Riverpod i generowaniem kodu

Zyskiem z adnotacji @riverpod jest to, że asynchroniczne ładowanie, cachowanie i parametry family stają się deklaratywne. Poproś o to wprost.

Wskazówka

Gotowy do wklejenia prompt na asynchroniczny provider Riverpod z generowaniem kodu:

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.

Jak ocenić wynik: musi zawierać dyrektywę part '*.g.dart'; i używać zunifikowanego Ref (Riverpod 3.x porzucił generowane per-provider refy w stylu UserProfileRef), a nie starego AutoDisposeFutureProviderRef. Jeśli gdziekolwiek widzisz StateNotifier, wróciło do starego stylu - odeślij to. Uruchom dart run build_runner build --delete-conflicting-outputs i potwierdź, że się kompiluje, zanim mu zaufasz.

Nawigacja z go_router

Przekierowanie autoryzacji w go_router to klasyczny błąd nieskończonej pętli: przekierowujesz niezalogowanych użytkowników do /login, ale zapominasz przepuścić samo /login przez bramkę, i router odbija się w nieskończoność.

Wskazówka

Gotowy do wklejenia prompt na przekierowanie autoryzacji go_router, które się nie zapętla:

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.

Sprawdź, czy przekierowanie zwraca null dla samych tras autoryzacji - ta jedna klauzula bramki jest tym, co zapobiega pętli, i jest linią, którą AI najczęściej pomija.

Networking z Dio

Wskazówka

Gotowy do wklejenia prompt na serwis API z Dio z interceptorami i ponawianiem:

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.

Oceniaj go po obsłudze błędów: ścieżka happy path jest trywialna, ale to odświeżenie tokenu z ponowieniem przy 401 oraz typowane ApiFailure czynią z tego kod produkcyjny. Jeśli AI tylko ponownie rzuca DioException, odeślij to z poleceniem „map every DioException to the sealed ApiFailure.”

Czysta architektura

W większych aplikacjach prompt o warstwy warto dopracować raz. Daj AI konkretną funkcję, a nie abstrakcyjne „ustaw czystą architekturę”.

Wskazówka

Gotowy do wklejenia prompt na wycinek funkcji w czystej architekturze:

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.

Ograniczenie, które ma znaczenie: warstwa domeny nie może importować Fluttera ani dio. Poproś AI o potwierdzenie tego, a potem wyrywkowo sprawdź importy - przeciekły package:flutter/material.dart w use case to sygnał, że podział na warstwy jest tylko kosmetyczny.

Testowanie

Wskazówka

Gotowy do wklejenia prompt na testy widgetów i golden:

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.

Gdy to się sypie

Tryby awarii poniżej to miejsca, gdzie Flutter + AI najczęściej idzie w bok:

• Dryf build_runner. Objawy: „conflicting outputs”, nieaktualny wygenerowany kod albo provider, który „nie istnieje”. Naprawa: dart run build_runner build --delete-conflicting-outputs, a jeśli dalej stawia opór, flutter clean, a potem regenerowanie. Wklej dokładny błąd build_runner do AI i poproś o ustalenie, czy przyczyną jest brakująca dyrektywa part, mieszanie starej składni z generowaniem kodu, czy niedopasowanie wersji między riverpod_annotation a riverpod_generator.
• Awarie Gradle i CocoaPods. Awarie buildu Androida po podbiciu zależności to zwykle niedopasowanie wersji Gradle/AGP lub Kotlina; awarie iOS to zwykle Pod, który potrzebuje pod repo update, albo wyższy docelowy poziom wdrożenia iOS. Wklej pełny log buildu i poproś AI o przypięcie konkretnych wersji - nie pozwól mu podbijać Flutter SDK, żeby „naprawić” problem z Podem.
• Niestabilność testów golden w CI. Goldeny renderowane lokalnie na macOS nie będą pasować piksel w piksel do runnera CI na Linuksie z powodu renderowania czcionek. Generuj i weryfikuj goldeny na jednym OS-ie albo wczytaj dołączoną czcionkę testową. Jeśli goldeny są niestabilne, poproś AI o dodanie flutter_test_config.dart, które wczytuje stałą czcionkę przed uruchomieniem testów.

Notatka

Dla samego CI podłącz oficjalny serwer GitHub MCP (https://api.githubcopilot.com/mcp/) - ten sam endpoint, konfigurowany per narzędzie: wpis github z tym url w .cursor/mcp.json dla Cursor, claude mcp add --transport http github https://api.githubcopilot.com/mcp/ dla Claude Code oraz blok [mcp_servers.github] w ~/.codex/config.toml dla Codex. Z podłączonym serwerem agent czyta Twoje rzeczywiste workflow i nazwy sekretów, zanim napisze zadanie flutter test + integration_test, zamiast wymyślać nazwy sekretów, które potem musisz poprawiać. Do triażu awarii na produkcji hostowany serwer Sentry MCP (https://mcp.sentry.dev/mcp) pozwala agentowi pobrać rzeczywisty stack trace i breadcrumbs dla wydania; jednorazowy skill nie da mu takiego żywego, odpytywalnego dostępu do Twoich błędów.

Co dalej

• Wzorce rozwoju Expo, jeśli porównujesz stosy cross-platform
• Wzorce React Native dla porównania po stronie JS
• Integracja backendu dla API, z którym rozmawia Twój ApiService