flutter-project-structure
Establishes a clean, modular architecture and project structure for Flutter applications.
SKILL.mdskills/flutter/project-structure/SKILL.md
GitHubFlutter Project Structure
Context
Apply when creating new features, modules, or navigating the codebase in a modular Flutter project.
Instructions
- Feature-first organization: Group by feature, not by type.
- Module structure:
lib/ ├── main.dart # Entry point ├── app.dart # MaterialApp / Router setup ├── core/ # Shared utilities, constants, extensions │ ├── constants/ │ ├── extensions/ │ ├── theme/ │ ├── utils/ │ ├── widgets/ # Shared/reusable widgets │ └── import/ # Centralized imports (app_imports.dart) ├── features/ # Feature-based modules │ ├── features.dart # Global barrel exporting all features │ └── <feature_name>/ │ ├── <feature_name>.dart # Feature root barrel │ ├── data/ │ │ ├── models/ │ │ │ └── index.dart │ │ ├── datasources/ │ │ │ └── index.dart │ │ └── repositories/ │ │ └── index.dart │ ├── domain/ │ │ ├── entities/ │ │ │ └── index.dart │ │ ├── repositories/ │ │ │ └── index.dart │ │ └── usecases/ │ │ └── index.dart │ └── presentation/ │ ├── providers/ │ │ └── index.dart │ ├── pages/ │ │ └── index.dart │ └── widgets/ │ └── index.dart ├── l10n/ # Localization └── injection/ # Dependency injection setup - Import rules:
- Features should NOT import from other features directly.
- Use the
core/layer for shared logic. - Data layer is accessed via repository interfaces in the domain layer.
- Widget decomposition: If a widget exceeds ~150 lines, decompose into smaller widgets.
- Barrel files (The "Deep Barrel" Pattern): Use a hierarchical barrel system to consolidate imports.
- Layer Barrels (
index.dart): Every leaf directory (entities, models, providers, etc.) MUST have anindex.dartexporting its handwritten contents.- ⚠️ Rule: Never export generated files (
.g.dart,.freezed.dart) in barrels.
- ⚠️ Rule: Never export generated files (
- Feature Barrels (
<feature_name>.dart): The feature root MUST have a barrel file named after the feature that exports all its layer-levelindex.dartfiles. - Global Features Barrel (
features.dart): Thelib/features/root MUST have afeatures.dartfile exporting all individual feature barrels. - This allows importing an entire feature via:
import 'package:<package_name>/features/<feature_name>/<feature_name>.dart';Or multiple features via:import 'package:<package_name>/features/features.dart';
- Layer Barrels (
- Centralized Imports: Use
lib/core/import/to consolidate common dependencies.packages_imports.dart: Exports all third-party packages (Flutter, Riverpod, etc.).app_imports.dart: Exportspackages_imports.dart+ allcorelayers + allfeatures.- ⚠️ Important: Add
// ignore_for_file: invalid_export_of_internal_elementat the top of these barrel files to allow exporting generator-internal members (like Riverpod's$types) without warnings. - This allows any file in the app to access most common logic with a single import:
import 'package:<package_name>/core/import/app_imports.dart'; - ⚠️ Rule: Always use
package:imports instead of relative paths for these centralized barrels to ensure project-wide consistency.
Anti-patterns
- ❌ Cross-feature imports (feature A importing from feature B directly)
- ❌ Business logic in widgets
- ❌ Monolithic files with
partdirectives for non-generated code - ❌ Deeply nested widget trees without extraction