Flutter Boilerplate

A production-grade starting point for Flutter apps: feature-first architecture, BLoC state management, a Dio network layer with typed failures and token refresh, go_router navigation with auth guards, compile-time environments, strict analysis, and tests at every layer.

It ships a small working app against the public DummyJSON demo API: sign in, browse a paginated list of posts, open one, sign out. The posts feature is the canonical example to copy.

Quick start

Requires Flutter 3.47+ (Dart 3.13+).

flutter pub get
flutter run --dart-define-from-file=config/development.json

Sign in with DummyJSON's public test account: emilys / emilyspass.

In VS Code, pick the Development launch configuration instead of typing the flag. Running without a config file fails at startup with a message that says which values are missing.

Commands

Task	Command
All checks (same as CI)	dart run tool/verify.dart
Format / analyze / test	dart format . · flutter analyze · flutter test
Integration test	flutter test integration_test -d <device-id>
New feature scaffold	dart run tool/new_feature.dart orders order
Rename for a new project	dart run tool/rename_project.dart --package my_app --org com.acme --name "My App"
Release build	flutter build appbundle --dart-define-from-file=config/production.json

Starting a new project from this template

1. Copy the repository (or use it as a GitHub template).
2. dart run tool/rename_project.dart --package my_app --org com.acme --name "My App"
3. Point API_BASE_URL in config/*.json at your backends.
4. Replace the DummyJSON-specific parts: endpoints in the data sources and the token payload in AuthTokensDto. Delete features/posts once your first feature exists.
5. Set up release signing (android/key.properties.example).
6. dart run tool/verify.dart

Structure

lib/
├── main.dart        entry point: calls bootstrap()
├── app/             composition root: bootstrap, root widget, config, router
├── core/            feature-agnostic infrastructure: error, logging, network,
│                    storage, theme, shared widgets
└── features/
    ├── auth/        session, sign-in, sign-out
    └── posts/       paginated list + detail: the reference feature

Each feature has data/ (DTOs, data sources, repository implementations), domain/ (entities, repository contracts) and presentation/ (blocs, pages, widgets). Dependencies point inward: app → features → core.

Documentation

Document	Covers
Architecture	Layers, dependency rules, data flow, where code goes
API layer	ApiClient, requests, decoding, retries, auth refresh
Error handling	AppFailure, Result, user messages, logging
Performance	Rebuild scoping, lists, networking, isolates
Testing	Test layout, fakes, bloc/widget/integration tests
Development	Setup, environments, tooling, platforms, git workflow
Agent workflow	How coding agents should work in this repository
Decisions (ADRs)	Why the architecture is the way it is