flutterator 3.1.5

A CLI to generate Flutter projects with DDD architecture

🚀 Flutterator

A CLI to generate and manage Flutter projects with DDD (Domain-Driven Design) architecture

Sito: flutterator.com · Repository: github.com/lorenzo9598/flutterator

---

📑 Table of Contents

• What is Flutterator?
• Installation
• Quick Start
• Available Commands
  • create - Create new project
  • add-domain - Add domain entity (model + infrastructure)
  • add-enum - Add domain enum
  • add-page - Add simple page
  • add-component - Add reusable component (form, list, single)
  • list - List project resources
  • config - Manage configuration
• Global Flags
• Configuration
• Generated Architecture
• Core: value objects and errors
• Testing
• Troubleshooting

---

📖 What is Flutterator?

Flutterator is a command-line tool that automates Flutter project creation following Domain-Driven Design (DDD) architecture best practices.

Instead of manually creating dozens of files for each new feature (entity, repository, bloc, page, dto...), Flutterator generates them automatically with a consistent and professional structure.

🎯 Problem It Solves

Creating a new feature in a Flutter DDD project requires:

• 📁 Creating 4+ folders (model, infrastructure, application, presentation)
• 📄 Creating 10+ Dart files (entity, failure, repository interface, dto, bloc, event, state, page...)
• ✏️ Writing boilerplate code for each file
• 🔗 Updating the router with new routes
• ⏱️ Estimated time: 30-60 minutes per feature

With Flutterator:

flutterator add-domain --name todo --fields "title:string,done:bool"
flutterator add-component --name todo_list --type list

Time: 5 seconds ⚡

💡 Who It's For

• Flutter developers using DDD/Clean Architecture
• Teams wanting to standardize code structure
• Freelancers wanting to speed up new project development
• Students wanting to learn DDD architecture with practical examples

---

📦 Installation

Requirements

• Python 3.8+
• Flutter SDK (for generated projects)

Installation from Source (Recommended)

# 1. Clone the repository
git clone https://github.com/lorenzo9598/flutterator.git
cd flutterator

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -e .

# 4. Verify installation
flutterator --help

Installation via pip (when published)

pip install flutterator

Verify Installation

flutterator --help

Expected output:

Usage: flutterator [OPTIONS] COMMAND [ARGS]...

  🚀 Flutterator - Flutter DDD Project Generator
  ...

---

🚀 Quick Start

Scenario 1: New Project

# 1. Create a new Flutter project with DDD structure
flutterator create --name my_app

# 2. Enter the project
cd my_app

# 3. Add a complete feature
flutterator add-domain --name todo --fields "title:string,done:bool,priority:int"
flutterator add-component --name todo_list --type list

# 5. Run the project
flutter run

Scenario 2: Existing Project

# 1. Go to your existing Flutter project
cd my_existing_flutter_app

# 2. Add features
flutterator add-domain --name user --fields "name:string,email:string"
flutterator add-component --name user_list --type list

Scenario 3: Preview Before Creating

# Use --dry-run to see what will be created without modifying anything
flutterator add-domain --name product --fields "name:string,price:double" --dry-run

---

📋 Available Commands

Command	Description	Typical Use
create	Create new Flutter DDD project	Project start
add-domain	Add domain entity (model, infrastructure)	Shared domain model
add-enum	Add Dart enum under domain	Types used in models
add-component	Add component (form, list, single)	UI + BLoC
add-page	Add simple page	Static pages
list	List pages (router) and domain models	Overview
config	Manage configuration	Customization

---

🔧 Command Details

flutterator create

Creates a new Flutter project with complete DDD architecture.

Syntax

flutterator create [OPTIONS]

Options

Option	Type	Required	Default	Description
--name	string	❌	-	Project name (snake_case)
--login	flag	❌	false	Include authentication

Usage Modes

1. Complete command line:

flutterator create --name my_app --login

2. Interactive mode (if you don't specify --name):

flutterator create

Project name: my_app
Does the project have login? [y/N]: y

Examples

# Basic project
flutterator create --name my_app

# Project with authentication
flutterator create --name my_app --login

# Interactive mode (asks for name and options)
flutterator create

Generated Structure

my_app/
├── lib/
│   ├── core/
│   │   ├── model/              # Value objects, failures, errors
│   │   │   ├── value_objects.dart
│   │   │   ├── value_failures.dart
│   │   │   └── value_validators.dart
│   │   ├── infrastructure/     # Firebase modules, helpers
│   │   │   ├── firebase_injectable_module.dart
│   │   │   └── utils.dart
│   │   └── presentation/       # Common widgets
│   │       └── app_widget.dart
│   ├── domain/                 # Domain entities (shared business entities)
│   ├── features/               # Features (use cases)
│   │   ├── home/
│   │   │   └── presentation/
│   │   │       └── home_page.dart
│   │   └── splash/
│   │       └── presentation/
│   │           └── splash_page.dart
│   ├── main.dart              # Entry point
│   ├── injection.dart         # Dependency injection setup
│   └── router.dart            # Routing with auto_route
├── pubspec.yaml               # Flutter dependencies
├── analysis_options.yaml
└── ...

---

flutterator add-domain

Adds a domain entity (model + infrastructure only).

Domain entities are shared business entities that can be used by multiple features. They do NOT include application or presentation layers.

Syntax

flutterator add-domain [OPTIONS]

Options

Option	Type	Required	Default	Description
--name	string	✅	-	Domain entity name
--fields	string	❌	-	Fields as name:type,name:type
--folder	string	❌	from config	Domain folder (default: "domain")
--dry-run	flag	❌	false	Preview without creating
--no-build	flag	❌	false	Skip flutter pub get
--non-interactive	flag	❌	false	No field prompts; use --fields or id-only (CI/tools)
--project-path	string	❌	.	Project path

Usage Modes

Command line:

flutterator add-domain --name todo --fields "title:string,done:bool,priority:int"

Interactive mode:

flutterator add-domain --name todo

Domain entity name: todo
Fields (name:type,name:type): title:string,done:bool,priority:int

Examples

# Domain entity with fields
flutterator add-domain --name todo --fields "title:string,done:bool,priority:int"

# Interactive mode (will prompt for fields)
flutterator add-domain --name user

# Preview what will be created
flutterator add-domain --name product --fields "name:string,price:double" --dry-run

# Custom domain folder
flutterator add-domain --name note --fields "title:string" --folder shared/domain

Generated Structure

lib/domain/todo/
├── model/
│   ├── todo.dart
│   ├── todo_failure.dart
│   ├── i_todo_repository.dart
│   ├── value_objects.dart
│   └── value_validators.dart
└── infrastructure/
    ├── todo_dto.dart
    ├── todo_service.dart
    ├── todo_mapper.dart
    └── todo_repository.dart

Field types and --fields

Use --fields as a comma-separated list of name:type. Commas inside angle brackets belong to the type (e.g. meta:Map<String,dynamic>,items:List<TodoItem> is two fields).

Recommended order: create enums with add-enum and any referenced domain entities before an entity that uses them in List<Other>, Map<String, Other>, or a bare Other field—Flutterator validates types against files under your configured domain folder.

Category	Examples in --fields	Generated domain usage
Primitives	title:string, count:int, price:double, done:bool, at:datetime	Wrapped value objects where applicable (String → Title-style VO)
Nullable	subtitle:string?, note:Note?, tags:List<String>?	Option<T> or nullable collections per generator rules
UniqueId	id is auto-added; optional UniqueId fields	Known value object
Collections	tags:List<String>, ids:Set<int>, scores:Map<String,int>, data:Map<String,dynamic>	List / Set / Map with validated inner types
Domain model	author:User (PascalCase, must exist)	Nested entity + mapper/DTO wiring
Enum	status:OrderStatus (PascalCase; use add-enum first)	Dart enum + serialization mapping

The same type grammar applies to add-component --type form --fields "..." when you pass inline fields instead of sourcing them from a domain model.

add-domain also regenerates lib/core/errors/error_localizer.dart so each entity’s {Name}Failure gets a matching localize{Name}Failure helper (see Core: value objects and errors).

---

flutterator add-enum

Adds a Dart enum file under lib/<domain_folder>/enums/ so you can reference it from add-domain --fields.

Syntax

flutterator add-enum [OPTIONS]

Options

Option	Type	Required	Default	Description
--name	string	✅	-	Enum name (PascalCase, e.g. OrderStatus)
--values	string	❌	-	Comma-separated values (e.g. pending,active,done)
--folder	string	❌	from config	Domain root folder
--dry-run	flag	❌	false	Preview without creating
--force	flag	❌	false	Overwrite existing file without prompt
--project-path	string	❌	.	Project path

Example

flutterator add-enum --name OrderStatus --values "pending,shipped,delivered"
flutterator add-domain --name order --fields "id:string,status:OrderStatus,total:double"

---

flutterator add-page

Adds a simple page without business logic.

Ideal for static pages like About, Settings, Privacy Policy, etc.

Syntax

flutterator add-page [OPTIONS]

Options

Option	Type	Required	Default	Description
--name	string	✅	-	Page name
--folder	string	❌	from config	Destination folder
--dry-run	flag	❌	false	Preview without creating
--no-build	flag	❌	false	Skip flutter pub get
--project-path	string	❌	.	Project path

Usage Modes

Command line:

flutterator add-page --name settings

Interactive mode:

flutterator add-page

Page name: settings

Examples

# Settings page
flutterator add-page --name settings

# About page with preview
flutterator add-page --name about --dry-run

# Page in specific folder
flutterator add-page --name privacy --folder pages

Generated Structure

lib/features/settings/
└── settings_page.dart

Also updates:

• lib/router.dart - Adds the new route

---

flutterator add-component

Adds a reusable component with optional BLoC.

Supports three types: single (single item), list (list with CRUD), and form (form with validation).

Syntax

flutterator add-component [OPTIONS]

Options

Option	Type	Required	Default	Description
--name	string	✅	-	Component name
--type	choice	❌	-	Type: form, list, or single
--fields	string	❌	-	Form fields (requires --type form)
--domain-model	string	❌	-	Domain entity file stem, or none (skips model prompt; non-interactive)
--use-all-model-fields	flag	❌	false	With form + domain model, include every field (skip selection prompt)
--folder	string	❌	from config	Destination folder (e.g. shared/widgets)
--dry-run	flag	❌	false	Preview without creating
--no-build	flag	❌	false	Skip flutter pub get
--project-path	string	❌	.	Project path

Three Component Types

1. Single Component (--type single or default) - Widget that displays a single item loaded by ID:

flutterator add-component --name user_card
# or
flutterator add-component --name user_card --type single

2. List Component (--type list) - Widget that displays a list of items with complete CRUD operations:

flutterator add-component --name todo_list --type list

3. Form Component (--type form) - Form with validation and field management:

flutterator add-component --name login --type form --fields "email:string,password:string"

Usage Modes

Command line:

# Single component (default)
flutterator add-component --name user_card

# List component
flutterator add-component --name todo_list --type list

# Form component
flutterator add-component --name login --type form --fields "email:string,password:string"

Interactive mode:

flutterator add-component

Component name: todo_list
Select component type:
  1. Single item (loads one item by ID)
  2. List (shows all items with CRUD operations)
  3. Form (form with validation)
Type (1-3): 2

Examples

# Single component (default)
flutterator add-component --name user_card

# List component with complete CRUD
flutterator add-component --name todo_list --type list

# Form component with fields
flutterator add-component --name login --type form --fields "email:string,password:string"

# Component in specific folder
flutterator add-component --name search_bar --folder shared/widgets

# Registration form
flutterator add-component --name registration --type form --fields "name:string,email:string,password:string"

Generated Structure

Single Component:

lib/user_card/
├── application/
│   ├── user_card_bloc.dart
│   ├── user_card_event.dart
│   └── user_card_state.dart
└── presentation/
    └── user_card_component.dart

List Component:

lib/todo_list/
├── application/
│   ├── todo_list_bloc.dart      # BLoC with getAll, create, update, delete
│   ├── todo_list_event.dart      # loadRequested, createRequested, updateRequested, deleteRequested
│   └── todo_list_state.dart      # initial, loading, loaded(List<Model>), error
└── presentation/
    └── todo_list_component.dart   # Widget with ListView and CRUD operations

Form Component:

lib/login/
├── application/
│   ├── login_form_bloc.dart
│   ├── login_form_event.dart
│   └── login_form_state.dart
└── presentation/
    └── login_component.dart

---

---

---

flutterator list

Lists pages and domain models in the project.

Shows all pages parsed from router.dart and all domain models from the domain/ folder.

Syntax

flutterator list [OPTIONS]

Options

Option	Type	Required	Default	Description
--project-path	string	❌	.	Project path

Examples

# List pages and models
flutterator list

Example Output

╭──────────────────────╮
│ 📋 Project: my_app   │
╰──────────────────────╯

📄 Pages:
   /home          → HomePage        (lib/features/home/home_page.dart)
   /              → SplashPage      (lib/features/splash/splash_page.dart)
   /settings      → SettingsPage     (lib/features/settings/settings_page.dart)

📦 Domain Models:
   todo           (lib/domain/todo/model/todo.dart)
   user           (lib/domain/user/model/user.dart)

📦 Features: todo/ ├── model/ │ ├── todo │ └── todo_failure ├── application/ │ └── todo_bloc └── presentation/ └── todo_page

user/ ├── model/ │ ├── user │ └── user_failure ...

📄 Pages: settings/ (1 file) about/ (1 file)

🧩 Components: user_card/ (standard) login/ (form)

🛤️ Routes: /home → HomePage /todo → TodoPage /settings → SettingsPage /user → UserPage

---

### `flutterator config`

**Manages Flutterator configuration.**

Allows viewing or creating the configuration file.

#### Syntax

```bash
flutterator config [OPTIONS]

Options

Option	Type	Description
--show	flag	Show current configuration
--init	flag	Create configuration file
--project-path	string	Project path

Examples

# Show current configuration
flutterator config --show

# Create configuration file
flutterator config --init

Output --show

╭─────────────────────── ⚙️  Configuration ────────────────────────╮
│ ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓                         │
│ ┃ Setting             ┃ Value         ┃                         │
│ ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩                         │
│ │ Feature Folder      │ features      │                         │
│ │ Component Folder    │ components    │                         │
│ │ Page Folder         │               │                         │
│ │ Use BLoC            │ ✅            │                         │
│ │ Use Freezed         │ ✅            │                         │
│ │ Auto Build Runner   │ ✅            │                         │
│ └─────────────────────┴───────────────┘                         │
╰─────────────────────────────────────────────────────────────────╯

📄 Project config: /path/to/project/flutterator.yaml

---

🏃 Global Flags

These flags are available for all add-* commands:

Flag	Description	Example
--dry-run	Preview without creating files	--dry-run
--no-build	Skip flutter pub get and build_runner	--no-build
--project-path	Specify project path	--project-path ../app

--dry-run Example

$ flutterator add-domain --name todo --fields "title:string" --dry-run
$ flutterator add-component --name todo_list --type list --dry-run

Output:

╭──────────────────────────╮
│ 🔍 DRY-RUN MODE          │
│ No files will be created │
╰──────────────────────────╯

🔧 Would add feature: todo
   Fields: id:string

📁 lib/todo/
├── 📁 model/
│   ├── 📄 todo.dart
│   ├── 📄 todo_failure.dart
│   ├── 📄 i_todo_repository.dart
│   └── ...
├── 📁 infrastructure/
│   └── ...
├── 📁 application/
│   └── ...
└── 📁 presentation/
    └── 📄 todo_page.dart

📝 Would update: lib/router.dart

──────────────────────────────────────────────────
ℹ️  Run without --dry-run to create these files

--no-build Example

# Faster: skip pub get and build_runner
flutterator add-domain --name todo --fields "title:string" --no-build
flutterator add-component --name todo_list --type list --no-build

# Then run manually when you want
flutter pub get
dart run build_runner build --delete-conflicting-outputs

---

⚙️ Configuration

Configuration Priority

Flutterator loads configuration from multiple sources (in priority order):

1. 🔴 CLI Flags (highest priority) - --folder features
2. 🟠 flutterator.yaml in project
3. 🟡 ~/.flutteratorrc global (home directory)
4. 🟢 Defaults (lowest priority)

Create Configuration

# Create flutterator.yaml in project
flutterator config --init

flutterator.yaml Example

# 📁 Default folders for generated code
defaults:
  feature_folder: "features"     # lib/features/todo/
  domain_folder: "domain"         # lib/domain/note/ (shared entities)
  component_folder: "features/components" # lib/features/components/user_card/
  auto_run_build_runner: true    # Runs build_runner after generation

# 🎨 UI Configuration (for future reference)
styling:
  primary_color: "#2196F3"
  secondary_color: "#FF9800"

~/.flutteratorrc Example (Global)

# Global configuration for all projects
defaults:
  feature_folder: "features"
  auto_run_build_runner: false  # Disable for all projects

---

🏗️ Generated Architecture

Flutterator generates projects following DDD (Domain-Driven Design) architecture with layer separation:

lib/
├── core/                        # 🔧 CORE - Shared code
│   ├── model/                   # Value objects, validation failures, errors
│   │   ├── value_objects.dart
│   │   ├── failures.dart        # ValueFailure<T> (Freezed)
│   │   ├── errors.dart          # UnexpectedValueError
│   │   └── value_validators.dart
│   ├── errors/
│   │   └── error_localizer.dart # Maps domain *Failure to UI strings
│   ├── infrastructure/          # DI modules, helpers
│   │   └── firebase_injectable_module.dart
│   └── presentation/            # Common widgets
│       └── app_widget.dart
│
├── domain/                      # 🏛️ DOMAIN ENTITIES - Shared entities
│   ├── auth/                    # Auth entity (shared)
│   │   ├── model/               # Entity, failures, repository interface
│   │   │   ├── user.dart
│   │   │   ├── user_profile.dart
│   │   │   └── i_auth_facade.dart
│   │   └── infrastructure/      # Repository implementation, DTOs
│   │       ├── firebase_auth_facade.dart
│   │       └── user_profile_repository.dart
│   │
│   └── note/                    # Example: Note entity (shared)
│       ├── model/
│       │   ├── note.dart
│       │   └── i_note_repository.dart
│       └── infrastructure/
│           └── note_repository.dart
│
├── features/                    # 📦 FEATURES - Specific use cases
│   ├── auth/                    # Auth feature (complete use case)
│   │   ├── application/         # ⚙️ APPLICATION LAYER
│   │   │   ├── auth_bloc.dart
│   │   │   ├── auth_event.dart
│   │   │   └── auth_state.dart
│   │   └── presentation/        # 🎨 PRESENTATION LAYER
│   │       └── login_page.dart
│   │
│   └── notes/                    # Example feature "note management"
│       │                          # (uses domain/note)
│       ├── application/         # ⚙️ APPLICATION LAYER
│       │   ├── notes_bloc.dart      # BLoC (logic)
│       │   ├── notes_event.dart     # Events
│       │   └── notes_state.dart     # States
│       │
│       └── presentation/        # 🎨 PRESENTATION LAYER
│           └── notes_page.dart      # UI
│
├── shared/                      # 🧩 SHARED - Shared components
│   └── widgets/
│
├── main.dart                    # Entry point
├── injection.dart               # 💉 Dependency Injection
└── router.dart                  # 🛤️ Routing (auto_route)

Why DDD?

Benefit	Description
Testability	Each layer is isolated and testable
Maintainability	Organized and predictable code
Scalability	Easy to add new features
Team	Multiple developers can work in parallel

---

Core: value objects and errors

Generated projects share a small core model for validated inputs and user-visible failures.

File	Role
lib/core/model/value_validators.dart	Pure functions returning Either<ValueFailure<T>, T> (e.g. max length, not empty). Composed with flatMap inside each domain value object factory.
lib/core/model/value_objects.dart	Abstract ValueObject<T> holding Either<ValueFailure<T>, T>, plus helpers like getOrCrash(), failureOrUnit, and shared types (UniqueId, …).
lib/core/model/failures.dart	Freezed ValueFailure<T> variants (validation errors: empty string, list too long, invalid email, …). Extension ValueFailureX can expose default title / message strings.
lib/core/model/errors.dart	UnexpectedValueError — thrown when code calls getOrCrash() on an invalid value object.
lib/core/errors/error_localizer.dart	Maps each domain entity’s {Entity}Failure (in lib/.../model/*_failure.dart) to a user-facing string via localize{Entity}Failure. Regenerated when you add domain entities; optional localizeAuthFailure when auth exists. Template comments show how to swap strings for l10n.

Domain *Failure vs ValueFailure: {Entity}Failure (e.g. TodoFailure) models business / IO problems (not found, permission denied, …) used by repositories and BLoCs. ValueFailure models invalid field input at the value-object layer.

---

📚 Flutter Generated Dependencies

Generated projects use these standard Flutter dependencies:

Package	Purpose	Link
flutter_bloc	State management	pub.dev
freezed	Immutable classes	pub.dev
injectable	Dependency injection	pub.dev
auto_route	Declarative routing	pub.dev
dartz	Functional programming	pub.dev
json_annotation	JSON serialization	pub.dev

---

🧪 Testing

# Activate virtual environment
source venv/bin/activate

# Run all tests
pytest tests/ -v

# Only fast tests (without E2E)
pytest tests/test_basic.py tests/test_integration.py -v

# Only E2E tests (requires Flutter SDK installed)
pytest tests/test_e2e_flutter.py -v

# With coverage
pytest tests/ --cov=. --cov-report=html

---

🔧 Troubleshooting

"Command not found: flutterator"

# Make sure you installed correctly
pip install -e .

# Or use python directly
python flutterator.py --help

flutterator --help shows only "create" (no add-domain, add-page, etc.)

You are using an old or different installation of Flutterator that only exposes the create command. The full CLI is a group of commands: create, add-domain, add-enum, add-page, add-component, list, config.

Fix:

1. Check which executable runs: which flutterator
2. Use the CLI from this repo:

   cd /path/to/flutterator   # this repo root
   python3 flutterator.py --help
   

   You should see "Usage: flutterator [OPTIONS] COMMAND [ARGS]..." and the list of commands.
3. Either:
   • Option A: Remove or rename the old flutterator from your PATH, then install from this repo: pip install -e . (requires pip ≥ 21.3), or
   • Option B: Add an alias so the repo’s CLI wins:

     alias flutterator='python3 /path/to/flutterator/flutterator.py'
     

     (Replace /path/to/flutterator with the real path to this repo.)

"Not a valid Flutter project"

# Flutterator requires pubspec.yaml and lib/
# Make sure you're in a valid Flutter project
ls pubspec.yaml lib/

"rich import error" in IDE

The IDE might not recognize the virtual environment. Solution:

1. Cmd+Shift+P → "Python: Select Interpreter"
2. Select ./venv/bin/python

build_runner slow

# Use --no-build to skip build_runner
flutterator add-domain --name todo --fields "title:string" --no-build
flutterator add-component --name todo_list --type list --no-build

# Run build_runner once at the end
dart run build_runner build --delete-conflicting-outputs

Dart compilation errors

After generating code, run:

flutter pub get
dart run build_runner build --delete-conflicting-outputs

---

🤝 Contributing

1. Fork the repository
2. Create branch: git checkout -b feature/new-feature
3. Commit: git commit -m 'Add new feature'
4. Push: git push origin feature/new-feature
5. Open Pull Request

Project Structure

flutterator/
├── flutterator.py              # Main CLI
├── generators/
│   ├── helpers/                # Helper functions
│   │   ├── config.py           # Configuration management
│   │   └── project.py          # Project validation
│   └── static/templates/       # Jinja2 templates
├── tests/                      # Test suite
└── docs/                       # Documentation

---

📄 License

MIT License - see LICENSE

---

👨‍💻 Author

Lorenzo Busi - GetAutomation

---

🙏 Acknowledgments

• Click - CLI framework
• Jinja2 - Template engine
• Rich - Terminal formatting
• Flutter - UI framework
• Reso Coder - DDD architecture inspiration

---

Generated with ❤️ by Flutterator