flutter-project-layout
/flutter-project-layout
Feature-based Flutter app layout — lib/main.dart, lib/src/app.dart, lib/src/core/ for shared infrastructure (Dio, Result, router + AppShell, theme, env, storage, shared components, formatting), and one folder per feature under lib/src/<feature>/ with api (Retrofit), models, repositories (repository + its provider file), providers, screens, and components; a barrel per feature and for core that exports every file and is the only import path; one central go_router in core; Env with --dart-define-from-file=.env; main.dart with async-created values and the retry policy; test/ mirroring lib/src. Us
- Author
- Dee9975 ↗
- Repository
- cc-skills-flutter ↗
- Licence
- MIT
- Last repository change
- 05.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Feature-based Flutter app layout — lib/main.dart, lib/src/app.dart, lib/src/core/ for shared infrastructure (Dio, Result, router + AppShell, theme, env, storage, shared components, formatting), and one folder per feature under lib/src/<feature>/ with api (Retrofit), models, repositories (repository + its provider file), providers, screens, and components; a barrel per feature and for core that exports every file and is the only import path; one central go_router in core; Env with --dart-define-from-file=.env; main.dart with async-created values and the retry policy; test/ mirroring lib/src. Us
Original author description
Feature-based Flutter app layout — lib/main.dart, lib/src/app.dart, lib/src/core/ for shared infrastructure (Dio, Result, router + AppShell, theme, env, storage, shared components, formatting), and one folder per feature under lib/src/<feature>/ with api (Retrofit), models, repositories (repository + its provider file), providers, screens, and components; a barrel per feature and for core that exports every file and is the only import path; one central go_router in core; Env with --dart-define-from-file=.env; main.dart with async-created values and the retry policy; test/ mirroring lib/src. Us
How it works
- The layout
- What goes where
- Repository provider file
- Barrels: one import per feature
- main.dart and app.dart
- Environment
- Routing
- Review checklist
SKILL.md preview
---
name: flutter-project-layout
description: "Feature-based Flutter app layout — lib/main.dart, lib/src/app.dart, lib/src/core/ for shared infrastructure (Dio, Result, router + AppShell, theme, env, storage, shared components, formatting), and one folder per feature under lib/src/<feature>/ with api (Retrofit), models, repositories (repository + its provider file), providers, screens, and components; a barrel per feature and for core that exports every file and is the only import path; one central go_router in core; Env with --dart-define-from-file=.env; main.dart with async-created values and the retry policy; test/ mirroring lib/src. Use when starting a Flutter project, adding a feature, deciding where a file belongs, or reviewing imports."
license: MIT
metadata:
author: Matiss Kalnins
version: "0.5.0"
---
**Persona:** You organize the app by feature. Everything `leaders` needs (its Retrofit API, models, repository, providers, screens, and components) lives under `lib/src/leaders/`. Shared infrastructure lives in `lib/src/core/`. Deleting a feature means deleting one folder and its routes.
## The layout
```
lib/
main.dart # creates async values, ProviderScope (overrides + retry), runApp
src/
app.dart # App: MaterialApp.router with light/dark theme and the router
core/
core.dart # barrel: exports every file in core/
api/dio_provider.dart # the single keepAlive Dio (base URL from Env)
components/ # widgets shared by 2+ features (ErrorView, TeamLogo, SectionHeader)
env/env.dart # Env: String.fromEnvironment values
formatting/stat_format.dart # shared formatters as static methods (StatFormat.percent)
models/ # models shared by 2+ features (LocalizedName)
result/result.dart # Result (Ok / Err), AppFailure and its subclasses
router/router.dart # the one GoRouter provider
router/app_shell.dart # bottom navigation around the tabs
storage/shared_preferences_provider.dart
theme/ # colors, color pairs, ref colors, spacing, text styles, ThemeData, dark mode
leaders/
leaders.dart # barrel: exports every file in the feature
api/leaders_api.dart # @RestApi Retrofit interface (+ generated .g.dart)
models/ # freezed + json_serializable models, enums, record typedefs
repositories/
leaders_repository.dart # wraps the API, returns Result
leaders_repository_provider.dart
providers/ # leaders_provider.dart, leaders_category_provider.dart, …
screens/leaders_screen.dart # route targets
components/ # leaders_list.dart, leader_row.dart, …
players/ schedule/ teams/ settings/
test/
helpers/fakes.dart # FakeXRepository classes + noRetry
helpers/fixtures.dart # fixture(name) loads test/fixtures/<name>.json
fixtures/*.json # real API responses
src/ # mirrors lib/src/
```
A feature only creates the folders it needs. `settings/` has just `screens/` and `components/`.
## What goes where
| Folder | Contains |
| --- | --- |
| `api/` | Retrofit `@RestApi` interfaces only (see `dart-networking`) |
| `models/` | freezed/json_serializable models, API enums, and record typedefs for UI-composed shapes (see `dart-json-serialization`) |
| `repositories/` | `<x>_repository.dart`, a concrete class wrapping one API and returning `Result`; and `<x>_repository_provider.dart`, the keepAlive provider that builds it |
| `providers/` | `<x>_provider.dart` files: fetching providers that unwrap repository results, derived providers, and selection Notifiers (see `flutter-riverpod`) |
| `screens/` | One widget per route: a `Scaffold` + `SafeArea` layout of components |
| `components/` | Everything else in the UI: self-connected lists and controls, plus rows and sections that take values (see `flutter-widgets`) |
The data path is always Retrofit API → repository → provider → widget. Widgets never call a repository or an API.
## Repository provider file
The repository provider builds the Retrofit API inline. There's no separate API provider:
```dart
// lib/src/leaders/repositories/leaders_repository_provider.dart
import "package:riverpod_annotation/riverpod_annotation.dart";
import "package:app/src/core/core.dart";
import "package:app/src/leaders/leaders.dart";
part "leaders_repository_provider.g.dart";
@Riverpod(keepAlive: true)
LeadersRepository leadersRepository(Ref ref) =>
LeadersRepository(LeadersApi(ref.watch(dioProvider)));
```
## Barrels: one import per feature
Every feature has a barrel named after it (`lib/src/leaders/leaders.dart`) that **exports every file in the feature**. `lib/src/core/core.dart` does the same for core. Code imports barrels, never individual files. That applies inside the feature as well as from outside it:
```dart
// lib/src/leaders/leaders.dart
export "api/leaders_api.dart";
export "components/leader_category_chips.dart";
export "components/leader_row.dart";
export "components/leaders_list.dart";
export "models/leader_category.dart";
export "models/leaderboard.dart";
export "models/stat_leader.dart";
export "providers/leaders_category_provider.dart";
export "providers/leaders_provider.dart";
export "repositories/leaders_repository.dart";
export "repositories/leaders_repository_provider.dart";
export "screens/leaders_screen.dart";
```
```dart
// lib/src/leaders/components/leader_row.dart
import "package:flutter/material.dart";
import "package:flutter_riverpod/flutter_riverpod.dart";
import "package:app/src/core/core.dart";
import "package:app/src/leaders/leaders.dart"; // its own feature's barrel
```
- **Add every new file to its barrel** in the same change. Generated `part` files aren't exported.
- Barrels never `show`/`hide`.
- Files importing their own barrel is fine, since Dart allows circular imports between libraries.
- **Names must be unique across the app**, since a file may import several barrels. Prefix generic names with the feature (`LeaderRow`, `StandingsList`).
- Features may import each other's barrels (the router imports all of them, and `teams` opens `players` screens). Keep the dependency one-directional where possible.
## main.dart and app.dart
```dart
// lib/main.dart
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final SharedPreferencesWithCache preferences =
await SharedPreferencesWithCache.create(
cacheOptions: const SharedPreferencesWithCacheOptions(
allowList: {DarkTheme.storageKey},
),
);
runApp(
ProviderScope(
overrides: [sharedPreferencesProvider.overrideWithValue(preferences)],
retry: (retryCount, error) => switch (error) {
Offline() || TimeoutFailure() when retryCount < 3 => Duration(
seconds: 1 << retryCount,
),
_ => null,
},
child: const App(),
),
);
}
```
```dart
// lib/src/app.dart
class const App({super.key}) extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) => MaterialApp.router(
title: "NHL",
theme: AppTheme.light,
darkTheme: AppTheme.dark,
themeMode: ref.watch(darkThemeProvider) ? .dark : .light,
routerConfig: ref.watch(routerProvider),
);
}
```
- Async-created values (shared preferences) are built in `main` and injected with `overrideWithValue` (see `flutter-riverpod`).
- The retry policy lives on the root `ProviderScope`. It retries only `Offline` and `TimeoutFailure`, at most 3 times, with exponential backoff.
## Environment
```dart
// lib/src/core/env/env.dart
abstract final class Env {
static const String webApiUrl = String.fromEnvironment("WEB_API_URL");
}
```
- Values come from a gitignored `.env` file in the project root (`WEB_API_URL=https://…`), passed at build time with `flutter run --dart-define-from-file=.env`.
- `--dart-define` values are compiled into the binary, so never treat them as secret.
## Routing
There's one router, `lib/src/core/router/router.dart`, which imports every feature barrel. Features don't export route lists (see `flutter-navigation`).
## Review checklist
- [ ] New code lives in the feature that owns it; `core/` holds only what 2+ features use
- [ ] Each repository has a `<x>_repository_provider.dart` that builds its API inline
- [ ] Every file is exported from its barrel; all imports go through `core/core.dart` and feature barrels
- [ ] Widgets reach data only through providers
- [ ] `test/` mirrors `lib/src/`, with fakes in `test/helpers/fakes.dart`
Versions
The database has no other skills named flutter-project-layout.
Database snapshot: 13.11.2026 · package version e2a3dd26eb1f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100project-structure-and-packages
Enforces Flutter/Dart project scaffolding where the layout makes defects greppable — a single-package app by default (feature-first under lib/features/, shared foundation split by role in core/ data/ services/ routing/ theme/ l10n/, a thin main.dart that calls bootstrap(), no… - 100dart-networking
HTTP networking in Dart and Flutter — dio with Retrofit-generated API clients (@RestApi, @GET/@POST, @Path/@Query/@Body, retrofit_generator) in each feature's api/ folder, token-based authentication through a Dio QueuedInterceptor (attach, single-flight refresh on 401 via a… - 100dart-n-flutter
Instructions for writing Dart and Flutter code following the official recommendations. Triggers on: **/*.dart - 100flutter-feature-based-clean-architecture
Organize Flutter apps with modular feature-based clean architecture. Use when creating features under lib/features/ with domain, data, and presentation layers. Do not use for test-only, BlocBuilder, navigation, or spinner requests. - 100dart-expert
Expert-level Dart, Flutter, mobile development, and cross-platform apps. Use when the user mentions Flutter, mobile, cross platform, or widgets, or when the task involves Dart Language or Flutter Framework. - 100mobiai-flutter
Use when working on a Flutter or Dart project — building, testing, debugging, understanding state management and project structure.