mobile-flutter

Mobile Flutter Stack

Cross-platform mobile app stack:

Flutter - UI framework (iOS, Android, macOS, Web)
Riverpod - State management (not Provider/ChangeNotifier)
go_router - Declarative routing with deep linking
dio - HTTP client with interceptors
storybook_toolkit - Component development with device frames

No code generation. Models use hand-written fromJson/toJson.

Optional: drift (local SQLite)

For offline-first apps that need a local relational database, add drift. This is the one exception to the no-codegen rule — drift generates typed query code from table definitions. See offline-first.md for setup and patterns.

Environment Setup

Use asdf to manage Flutter and all tool versions:

# Install Flutter plugin (one-time)
asdf plugin add flutter

# Set project Flutter version
asdf set flutter latest

# Also set support tools as needed
asdf set ruby latest
asdf set cocoapods latest
asdf set rust latest  # needed by some native deps

This creates a .tool-versions file in the project root. Never use the official Flutter installer, mise, or other version managers.

MCP Setup

If .mcp.json doesn't exist in the project root, create it with this content:

{
  "mcpServers": {
    "dart": {
      "type": "stdio",
      "command": "dart",
      "args": [
        "mcp-server"
      ],
      "env": {}
    }
  }
}

This wires up dart mcp-server so the agent can drive the app, inspect widgets, capture screenshots, and analyze files. See mcp-driving-and-screenshots.md for usage.

Reference Files

File	When to Use
setup-guide.md	Starting a new Flutter project from scratch
patterns.md	Riverpod providers, repositories, screen architecture
offline-first.md	Adding drift for local SQLite, offline download/collect/sync
storybook.md	Setting up storybook, adding stories, mock data
gotchas.md	Common mistakes and platform-specific issues
mcp-driving-and-screenshots.md	Launching, driving (tap/type), debugging, and screenshotting a running app via the Dart MCP — and delivering screenshots to the user
mcp.json	Sample `.mcp.json` for the project root — copy here if it doesn't exist

Companion Skills

This skill defines the stack; pair it with the foundational Dart & Flutter agent skills that apply to essentially any project on it. Install them into a project with npx skills (the agent is auto-detected, so -y runs non-interactively):

# Quality, testing & debugging foundations
npx skills add dart-lang/skills \
  -s dart-run-static-analysis \
  -s dart-add-unit-test \
  -s dart-fix-runtime-errors -y

npx skills add flutter/skills \
  -s flutter-apply-architecture-best-practices \
  -s flutter-add-widget-test \
  -s flutter-add-integration-test -y

Skill	Why it's foundational
`dart-run-static-analysis`	`dart analyze` + `dart fix --apply` — during dev and before every commit
`dart-add-unit-test`	unit tests for logic with `package:test`
`dart-fix-runtime-errors`	stack-trace → fix → `hot_reload` loop
`flutter-apply-architecture-best-practices`	layered UI/logic/data structure (complements patterns.md)
`flutter-add-widget-test`	component-level tests with `WidgetTester`
`flutter-add-integration-test`	Flutter Driver / `integration_test` harness — pairs with mcp-driving-and-screenshots.md

Everything else is project-dependent — pick based on what the app actually does (JSON serialization, declarative routing, localization, responsive layout, HTTP, drift, coverage, mocks, pattern matching, …). Browse the full catalogs and --list to choose:

Dart: https://github.com/dart-lang/skills — npx skills add dart-lang/skills --list
Flutter: https://github.com/flutter/skills — npx skills add flutter/skills --list

Quick Reference

Commands

# Install dependencies
flutter pub get

# Run on macOS (local dev)
flutter run -d macos

# Run storybook
flutter run -d macos -t lib/storybook/main.dart

# Run on web
flutter run -d chrome

# Analyze
flutter analyze lib/

Package Management

Always use CLI commands — never edit pubspec.yaml directly:

# Add runtime dependency
flutter pub add <package>

# Add dev dependency
flutter pub add --dev <package>

# Add from git
flutter pub add --dev storybook_toolkit --git-url https://github.com/org/repo.git --git-ref branch-name

Project Structure

├── lib/
│   ├── main.dart           # App entrypoint
│   ├── app.dart            # MaterialApp.router + GoRouter + theme
│   ├── models/             # Plain Dart classes with fromJson/toJson
│   ├── providers/          # Riverpod providers
│   ├── repositories/       # Abstract interfaces + implementations
│   ├── database/           # drift tables + generated code (if using drift)
│   ├── screens/            # One directory per route
│   ├── storybook/          # Storybook entrypoint + mock data
│   ├── widgets/            # Shared reusable widgets
│   └── constants/          # Theme, colors, typography
├── specs/                  # Feature specifications (if using spec-first)
├── .env                    # Environment config (gitignored)
├── .env.example            # Template
└── pubspec.yaml

Architecture Layers

Screens (widgets)        → read from providers, dispatch actions
Providers (Riverpod)     → async state, business logic
Repositories (abstract)  → data access boundary
API Client / Local DB    → external boundaries

Screens never call repositories directly — always through providers. Repositories are abstract interfaces with real and fake implementations. Fakes are injected via Riverpod provider overrides in storybook and tests.

Key Patterns

// Riverpod provider
final stationsProvider = FutureProvider<List<Station>>((ref) {
  return ref.watch(stationRepositoryProvider).getAll();
});

// Family provider (parameterized)
final stationProvider = FutureProvider.family<Station?, String>((ref, id) {
  return ref.watch(stationRepositoryProvider).get(id);
});

// Consumer widget
class MyScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final dataAsync = ref.watch(stationsProvider);
    return dataAsync.when(
      data: (stations) => ListView(...),
      loading: () => CircularProgressIndicator(),
      error: (e, _) => Text('Error: $e'),
    );
  }
}

// Navigation with go_router
context.push('/items/${item.id}');  // push onto stack
context.go('/login');               // replace stack

Common Gotchas

Package management: Use flutter pub add, never edit pubspec.yaml directly

VSCode SDK path: Use ~ not ${env:HOME} in .vscode/settings.json:

{"dart.flutterSdkPath": "~/.asdf/installs/flutter/3.41.6-stable"}

macOS entitlements: Network requests need com.apple.security.network.client, keychain needs keychain-access-groups — both in macos/Runner/DebugProfile.entitlements and Release.entitlements
macOS signing: Set development team in Xcode (Runner target → Signing & Capabilities → Team → All configurations)
Commit generated code separately: After any command that generates/changes code, commit those changes with the exact command in the message BEFORE making manual edits