Flutter Feature Maker 🚀

A powerful, production-ready CLI tool for generating Flutter feature structures using clean architecture principles and built-in templates.

✨ Features

🏗️ Clean Architecture: Built with SOLID principles and separation of concerns
📦 Built-in Templates: Pre-configured templates for Clean, MVC, MVVM, and Clean Simple architectures
🎨 Custom Templates: Create and save your own folder structure templates
🎯 State Management Support: Built-in support for BLoC, Cubit, Provider, Riverpod, and GetX
🎨 Beautiful CLI: Colored output with clear progress indicators
🔄 Smart Placeholders: Use {STATE_MANAGEMENT} to dynamically inject state management folders
📝 Auto-generated Boilerplate: Generates compiling starter code — a screen widget plus idiomatic state-management skeletons (BLoC/Cubit classes with part files, ChangeNotifier, Riverpod Notifier, or GetxController)
🧭 Architecture Advisor: Warns (without blocking) when a template + state-management pairing is a conceptual mismatch, e.g. BLoC inside an MVC controller

🏛️ Architecture

This tool follows clean architecture with four distinct layers:

lib/
├── src/
│   ├── domain/              # Business logic layer
│   │   ├── entities/        # Core business entities
│   │   └── repositories/    # Repository interfaces
│   ├── infrastructure/      # External implementations
│   │   ├── file_system_impl.dart
│   │   ├── json_template_repository.dart
│   │   ├── json_config_repository.dart
│   │   ├── terminal_input_impl.dart
│   │   ├── state_management_registry.dart
│   │   └── storage_service.dart
│   ├── application/         # Use cases & services
│   │   ├── create_feature_service.dart
│   │   ├── save_template_service.dart
│   │   ├── delete_template_service.dart
│   │   ├── list_templates_service.dart
│   │   ├── list_state_management_service.dart
│   │   ├── config_service.dart
│   │   ├── state_management_boilerplate.dart  # Starter-code generator
│   │   └── architecture_advisor.dart          # Pairing advisories
│   ├── cli/                 # Presentation layer
│   │   ├── commands/        # Command implementations (one per command)
│   │   ├── colors.dart      # Terminal color utilities
│   │   ├── printer.dart     # Output formatting
│   │   └── command_runner.dart
│   └── utils/               # Shared utilities (string_utils, path_validator)
bin/
└── feature_maker.dart       # Entry point

📦 Installation

Global Installation (recommended)

Install the CLI from pub.dev:

dart pub global activate flutter_feature_maker

This gives you three interchangeable commands: ffm, feature_maker, and flutter_feature_maker. If ffm isn't found afterwards, add pub's bin directory to your PATH:

export PATH="$PATH:$HOME/.pub-cache/bin"   # add to ~/.zshrc or ~/.bashrc

From source (for development)

git clone https://github.com/Abdallahabusnineh/flutter_feature_maker
cd flutter_feature_maker
dart pub global activate --source path .

🚀 Usage

Create a Feature

Generate a new feature using a template:

feature_maker create

The tool will guide you through:

Selecting a template (built-in or custom)
Choosing state management (bloc, cubit, provider, riverpod, getx)
Entering the feature name

Example:

$ feature_maker create

📚 Available templates:
   Built-in:
   1. Clean
   2. MVC
   3. MVVM
   4. CLEAN_SIMPLE

📝 Enter template name (or number): 1

🎯 Select State Management:
   1. bloc
   2. cubit
   3. provider
   4. riverpod
   5. getx

📝 Enter state management (name or number): bloc

🎯 Enter feature name: Authentication

✅ Created: lib/features/authentication/domain/entities
✅ Created: lib/features/authentication/domain/repositories
...
✨ Flutter feature "authentication" created successfully with bloc!

Save Custom Template

Create and save your own template:

feature_maker save-template [options]

Options:

--global, -g: Save template globally (accessible in all projects)
--local, -l: Save template locally (specific to this project)

If no option is provided, the tool will ask you where to save it.

Example:

$ feature_maker save-template

📝 Enter template name: MyCustomTemplate

💾 Save globally (user home) or locally (project)? [G/l]: l
...
✅ Template "MyCustomTemplate" saved successfully!
Saved to: Local (./)

List Templates

View all available templates with their location:

feature_maker list-templates

Output Example:

📚 Available templates:
   Built-in:
   1. Clean
   2. MVC

   Custom:
   1. MyCustomTemplate (Local)
   2. SharedTemplate (Global)

Delete Template

Delete a custom template:

feature_maker delete-template [options]

Options:

--global, -g: Delete from global storage
--local, -l: Delete from local storage

List State Management Options

View all state management options:

feature_maker list-state-management

Help

Display help information:

feature_maker help

🎯 Built-in Templates

Clean Architecture

Full clean architecture with all layers:

domain/entities
domain/repositories
domain/usecases
data/datasources
data/models
data/repositories
{STATE_MANAGEMENT}
presentation/screens
presentation/widgets

MVC

Model-View-Controller pattern:

models
view
controllers

MVVM

Model-View-ViewModel pattern:

models
view
viewmodels
services

CLEAN_SIMPLE

Simplified clean architecture:

data/models
data/datasources
data/repository
{STATE_MANAGEMENT}
presentation/screens
presentation/widgets

🎨 State Management Options

Name	Folder	Generated files	Add this package to your app
bloc	`bloc`	`_bloc.dart`, `_event.dart`, `*_state.dart`	`flutter_bloc`
cubit	`cubit`	`_cubit.dart`, `_state.dart`	`flutter_bloc`
provider	`providers`	`*_provider.dart` (`ChangeNotifier`)	`provider`
riverpod	`providers`	`*_provider.dart` (`Notifier` + provider)	`flutter_riverpod`
getx	`controllers`	`*_controller.dart` (`GetxController`)	`get`

Note: The generated files import the package for your chosen option, so the scaffolded code compiles once you add that dependency to your Flutter app (e.g. flutter pub add flutter_bloc). Feature Maker itself has no Flutter dependency — it only writes text files.

🔧 Configuration

The tool supports Global (user-wide) and Local (project-specific) configuration. Local configuration always overrides global configuration.

Storage Locations

Global storage lives in each OS's conventional config directory:

OS	Global directory
macOS	`~/Library/Application Support/feature_maker/`
Linux	`$XDG_CONFIG_HOME/feature_maker/` (else `~/.config/feature_maker/`)
Windows	`%APPDATA%\feature_maker\` (else `%USERPROFILE%\feature_maker\`)

Global Config: config.json in the directory above
Global Templates: templates.json in the directory above
Local Config: ./.feature_maker_config.json
Local Templates: ./.feature_maker_templates.json

Feature Path

You can configure where features are created using the config command or create flags.

Default Resolution Order:

CLI Flag (--path)
Local Config (Project root)
Global Config (User home)
Default (lib/features/)

Managing Configuration

# Set global default path (for all projects)
feature_maker config --set-path src/modules --global

# Set local override (just for this project)
feature_maker config --set-path lib/app/features --local

# View resolved configuration
feature_maker config --show

# Reset configuration
feature_maker config --reset --local   # Reset local override
feature_maker config --reset --global  # Reset global default

Override per Command

# Create in specific folder (ignoring config)
feature_maker create --path lib/screens

📝 Generated Files

Screen File

The tool automatically generates a basic screen file:

import 'package:flutter/material.dart';

class AuthenticationScreen extends StatelessWidget {
  const AuthenticationScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: Text('AuthenticationScreen'),
      ),
    );
  }
}

State-management Files

Each option generates compiling starter code (not empty files). For BLoC, three part-linked files are created:

// authentication_bloc.dart
import 'package:flutter_bloc/flutter_bloc.dart';

part 'authentication_event.dart';
part 'authentication_state.dart';

class AuthenticationBloc extends Bloc<AuthenticationEvent, AuthenticationState> {
  AuthenticationBloc() : super(AuthenticationInitial()) {
    on<AuthenticationEvent>((event, emit) {
      // TODO: handle events and emit new states.
    });
  }
}

Cubit generates a Cubit + state, Provider a ChangeNotifier, Riverpod a Notifier + NotifierProvider, and GetX a GetxController. See the State Management Options table for the exact files and the package each expects.

🎨 Naming Conventions

Folders & Files: snake_case (e.g., authentication_screen.dart)
Classes: PascalCase (e.g., AuthenticationScreen)
Feature Path: lib/features/<feature_name>/

🔄 Placeholder System

Use {STATE_MANAGEMENT} as a placeholder in your templates. It will be automatically replaced with the correct state management folder based on your selection:

{STATE_MANAGEMENT} → presentation/bloc        (bloc)
{STATE_MANAGEMENT} → presentation/cubit       (cubit)
{STATE_MANAGEMENT} → presentation/providers   (provider and riverpod)
{STATE_MANAGEMENT} → presentation/controllers (getx)

🛠️ Development

Project Structure

flutter_feature_maker/
├── bin/
│   └── feature_maker.dart          # Entry point
├── lib/
│   └── src/
│       ├── domain/                 # Domain layer
│       ├── infrastructure/         # Infrastructure layer
│       ├── application/            # Application layer
│       ├── cli/                    # CLI layer
│       └── utils/                  # Utilities
├── pubspec.yaml
└── README.md

Running Tests

flutter test

Code Quality

The project follows Flutter's recommended lints and maintains clean architecture principles.

🎯 Design Decisions

1. Clean Architecture

Why: Ensures maintainability, testability, and scalability
Benefit: Easy to extend with new features without breaking existing code

2. Dependency Injection

Why: Loose coupling between layers
Benefit: Easy to test and swap implementations

3. Command Pattern

Why: Each command is isolated and follows single responsibility
Benefit: Easy to add new commands without modifying existing code

4. Repository Pattern

Why: Abstracts data source operations
Benefit: Can easily switch from JSON to database storage

5. Strategy Pattern (State Management)

Why: Flexible state management selection
Benefit: Easy to add new state management options

🚀 Future Enhancements

Support for multiple file generation templates
Interactive template editor
Template sharing via GitHub
Integration with CI/CD pipelines
Template validation and linting
Support for custom file content templates
Export/import template collections

📄 License

MIT License - feel free to use this tool in your projects!

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch
Follow the clean architecture pattern
Write tests for new features
Submit a pull request

📞 Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.

Made with ❤️ for the Flutter community