Clean Feature Architecture

CLI and analyzer for scaffolding and enforcing Feature-First Clean Architecture boundaries in Flutter projects.

pub package License: MIT Platform Interactive Sandbox

An interactive sandbox is available to explore Feature-First Clean Architecture layers and dependency boundaries.

Installation

Add the toolkit to your dev_dependencies:

dart pub add -d clean_feature_arch

Features

Modern Dart 3.x Support

Scaffolded templates utilize modern Dart standards:

  • Switch Expressions: Functional and exhaustive UI state rendering.
  • Record Destructuring: Declarative application initialization and result handling via AppRunner.
  • Enhanced Enums: Type-safe configuration and flavor management.
  • Sealed Classes: Compiler-verified state and error handling.

Modular Dependency Injection

Dependency injection follows a Modular Registry Pattern:

  • Core Module: Centralized management for infrastructure, network, and storage.
  • Feature Modules: Localized registration logic within each feature's di/ directory.
  • Dispatcher: A clean injection_container.dart that coordinates modular registries.

CLI Usage

All commands are executed via dart run clean_feature_arch:

1. Project Initialization

Initializes the core architecture (Router, Theme, Storage, Networking) and shared resources (Assets, Localization, Context Extensions).

# Default
dart run clean_feature_arch init

# With BLoC or Riverpod
dart run clean_feature_arch init --state bloc
dart run clean_feature_arch init --state riverpod

2. Feature Generation

Creates the domain, data, and presentation layers for a new feature.

dart run clean_feature_arch feature <name> --state [bloc|riverpod|none] --storage [drift|shared|none]

3. Storage Management

Configure storage engines or integrate them into existing features.

# Initialize a global engine (Drift or Shared Preferences)
dart run clean_feature_arch storage init

# Add storage to an existing feature
dart run clean_feature_arch storage feature <name> --type [drift|shared]

4. Permission Configuration

Configure system permissions across all supported platforms.

# Interactive menu
dart run clean_feature_arch permission

# Direct command
dart run clean_feature_arch permission camera

5. CI/CD Scaffolding

Generate automated workflows for GitHub Actions or GitLab CI.

dart run clean_feature_arch ci

6. Test Scaffolding

Initialize unit and integration test infrastructure.

# Core infrastructure tests
dart run clean_feature_arch test --init

# Feature-specific test suite
dart run clean_feature_arch test <feature_name>

7. Terminal Documentation

Access technical references directly from the terminal.

# Display the Absolute Rules
dart run clean_feature_arch docs rules

# Display the project skeleton
dart run clean_feature_arch docs skeleton

Static Analysis

A modern Dart Analysis Server plugin (package:analysis_server_plugin) automatically enforces architectural boundaries and standards.

Automatic Discovery

In Dart 3.13+, analyzer plugins are discovered automatically when added to dev_dependencies in pubspec.yaml. No deprecated analyzer: plugins: configuration in analysis_options.yaml is needed:

dev_dependencies:
  clean_feature_arch: ^1.7.6

Architectural Rules Enforced

The analyzer plugin inspects import URI paths and project directory structures to validate layer conventions:

  • absolute_rule_avoid_illegal_layer_imports: Flags domain files containing imports with /data/ or /presentation/ path segments.
  • absolute_rule_enforce_feature_isolation: Flags files importing internal paths from different feature directories.
  • absolute_rule_enforce_model_folder_structure: Validates that model files reside in designated layer directories.
  • absolute_rule_prefer_sealed_freezed_models: Checks that domain models and states use sealed classes or @freezed.
  • absolute_rule_enforce_data_source_folder_structure: Validates data source organization under local_data_sources and remote_data_sources.

Severity Customization (Optional)

To elevate or suppress specific rules, configure them via the standard analyzer: errors: section in analysis_options.yaml:

analyzer:
  errors:
    absolute_rule_avoid_illegal_layer_imports: error
    absolute_rule_enforce_feature_isolation: warning

Documentation

Detailed technical guides:

License

Distributed under the MIT License. See LICENSE for details.

Libraries

clean_feature_arch
Architecture toolkit for Flutter.
main