flutter_feature_maker 1.0.0

A CLI tool for scaffolding Flutter feature folders using clean architecture, built-in and custom templates, and state management support.

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:

1. Selecting a template (built-in or custom)
2. Choosing state management (bloc, cubit, provider, riverpod, getx)
3. 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:

1. CLI Flag (--path)
2. Local Config (Project root)
3. Global Config (User home)
4. 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:

1. Fork the repository
2. Create a feature branch
3. Follow the clean architecture pattern
4. Write tests for new features
5. Submit a pull request

📞 Support

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

---

Made with ❤️ for the Flutter community