Skip to content
Skills Library
Programming · Building & coding

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

Licence
MIT
Last repository change
05.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.

Licence

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

  1. The layout
  2. What goes where
  3. Repository provider file
  4. Barrels: one import per feature
  5. main.dart and app.dart
  6. Environment
  7. Routing
  8. Review checklist
Original SKILL.md headings · 178 lines, 863 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.