🎯 flutter_blueprint #

Enterprise-grade Flutter app scaffolding CLI — generates production-ready Flutter projects with 43+ professional files, complete architecture, authentication patterns, error handling, storage layers, and reusable widgets. Stop wasting hours on boilerplate — start building features from day one.

🚀 Why flutter_blueprint? #

flutter_blueprint is not just a template — it's a smart code generator that creates production-grade architecture tailored to your choices.

✨ Features #

Core Features #

Professional Add-ons (What Makes It Pro) #

📦 Installation #

Global Activation (Recommended) #

dart pub global activate flutter_blueprint

Then use it anywhere:

flutter_blueprint init my_app

Local Execution #

dart run flutter_blueprint init my_app

🎬 Quick Start #

✨ Interactive Wizard Mode (Recommended) #

Just run without arguments for a beautiful guided experience:

flutter_blueprint init

What happens:

🎯 Welcome to flutter_blueprint!
   Let's create your Flutter app with professional architecture.

✔ 📱 App name · my_awesome_app

✔ 🎯 Choose state management · provider
   • Provider (ChangeNotifier, easy to learn)
   • Riverpod (Compile-time safe, better testability) ← NEW!
   • Bloc (Event-driven, coming soon)
   [Use ↑↓ arrow keys, Enter to select]

✔ ✨ Select features to include (use space to select, enter to confirm)
   ✓ Theme system (Light/Dark modes)
   ✓ Localization (i18n support)
   ✓ Environment config (.env)
   ✓ API client (Dio + interceptors)
   ✓ Test scaffolding

📋 Configuration Summary:
   App name: my_awesome_app
   State management: provider
   Theme: ✅
   Localization: ✅
   Environment: ✅
   API client: ✅
   Tests: ✅

✔ 🚀 Ready to generate your app? · yes

🚀 Generating project structure...
✅ Generated 43 files successfully!

Features:

• 🎨 Beautiful UI with emojis and colors
• ⌨️ Arrow key navigation for selections
• ☑️ Multi-select checkboxes for features (spacebar to toggle)
• ✅ Smart validation (prevents reserved words, invalid names)
• 📋 Configuration preview before generation

⚡ Quick Mode (For Experienced Users) #

Skip the wizard by providing the app name:

flutter_blueprint init my_app

Add flags for full control:

# Provider template (classic ChangeNotifier pattern)
flutter_blueprint init my_app \
  --state provider \
  --theme \
  --env \
  --api \
  --tests

# Riverpod template (compile-time safe with StateNotifier)
flutter_blueprint init my_app \
  --state riverpod \
  --theme \
  --env \
  --api \
  --tests
  --no-localization

Hybrid Mode (Mix Both) #

flutter_blueprint init my_app --state riverpod
# Prompts for remaining options

🎯 State Management Templates #

flutter_blueprint supports multiple state management patterns — choose the one that fits your team and project best!

📊 Comparison Table #

🟢 Provider Template #

When to use: You want simplicity, familiarity, and quick onboarding for new Flutter developers.

Example State Management:

// home_provider.dart
class HomeProvider extends ChangeNotifier {
  bool _isLoading = false;
  int _counter = 0;

  void incrementCounter() {
    _counter++;
    notifyListeners(); // Manual notification
  }
}

// home_content.dart
Consumer<HomeProvider>(
  builder: (context, provider, child) {
    return Text('Counter: ${provider.counter}');
  },
)

🟦 Riverpod Template (NEW!) #

When to use: You want compile-time safety, better testability, and you're building a large-scale app.

Example State Management:

// home_provider.dart
class HomeState {
  final bool isLoading;
  final int counter;

  HomeState({required this.isLoading, required this.counter});

  HomeState copyWith({bool? isLoading, int? counter}) {
    return HomeState(
      isLoading: isLoading ?? this.isLoading,
      counter: counter ?? this.counter,
    );
  }
}

class HomeNotifier extends StateNotifier<HomeState> {
  HomeNotifier() : super(HomeState(isLoading: false, counter: 0));

  void incrementCounter() {
    state = state.copyWith(counter: state.counter + 1); // Immutable update
  }
}

final homeProvider = StateNotifierProvider<HomeNotifier, HomeState>((ref) {
  return HomeNotifier();
});

// home_content.dart
class HomeContent extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final homeState = ref.watch(homeProvider); // Auto-rebuild on changes
    return Column(
      children: [
        Text('Counter: ${homeState.counter}'),
        ElevatedButton(
          onPressed: () => ref.read(homeProvider.notifier).incrementCounter(),
          child: Text('Increment'),
        ),
      ],
    );
  }
}

Riverpod Benefits:

• ✅ No BuildContext needed - access providers anywhere
• ✅ Compile-time errors - typos caught immediately
• ✅ Immutable state - easier debugging with state history
• ✅ Auto-disposal - no memory leaks
• ✅ Better testing - use ProviderContainer for isolated tests
• ✅ Family & AutoDispose modifiers for advanced use cases

🟣 Bloc Template (Coming Soon!) #

When to use: You need event-driven architecture, complex business logic, or team is familiar with BLoC pattern.

Stay tuned for Bloc support!

🧩 Generated Project Structure (43+ Files!) #

my_app/
├── lib/
│   ├── main.dart                              # App entry point
│   ├── app/
│   │   └── app.dart                           # Root app widget with providers
│   ├── core/
│   │   ├── api/                               # 🌐 Network layer
│   │   │   ├── api_client.dart                #   Dio client with GET/POST/PUT/DELETE
│   │   │   ├── api_response.dart              #   Generic response wrapper
│   │   │   └── interceptors/
│   │   │       ├── auth_interceptor.dart      #   Auto-add auth tokens
│   │   │       ├── retry_interceptor.dart     #   Auto-retry failed requests
│   │   │       └── logger_interceptor.dart    #   Log all API calls
│   │   ├── config/
│   │   │   ├── app_config.dart                # 🎛️ App configuration
│   │   │   └── env_loader.dart                #   Dev/Stage/Prod environments
│   │   ├── constants/
│   │   │   ├── app_constants.dart             # 📋 Timeouts, storage keys, pagination
│   │   │   └── api_endpoints.dart             #   Centralized API routes
│   │   ├── errors/
│   │   │   ├── exceptions.dart                # 🚨 9 custom exception types
│   │   │   └── failures.dart                  #   Clean architecture failures
│   │   ├── network/
│   │   │   └── network_info.dart              # 📡 Connectivity monitoring
│   │   ├── routing/
│   │   │   ├── app_router.dart                # 🧭 Route management
│   │   │   ├── route_guard.dart               #   Auth guards
│   │   │   └── route_names.dart               #   Centralized route constants
│   │   ├── storage/
│   │   │   ├── local_storage.dart             # 💾 SharedPreferences wrapper
│   │   │   └── secure_storage.dart            #   Secure token storage
│   │   ├── theme/
│   │   │   ├── app_theme.dart                 # 🎨 Light/Dark themes
│   │   │   ├── app_colors.dart                #   Color palette
│   │   │   └── typography.dart                #   Text styles
│   │   ├── utils/
│   │   │   ├── logger.dart                    # 📝 Pro logger (debug/info/warn/error)
│   │   │   ├── validators.dart                #   Form validators (email/phone/etc)
│   │   │   └── extensions.dart                #   String/DateTime/Context extensions
│   │   └── widgets/                           # 🧩 Reusable UI components
│   │       ├── loading_indicator.dart         #   Loading spinner
│   │       ├── error_view.dart                #   Error display with retry
│   │       ├── empty_state.dart               #   Empty list placeholder
│   │       ├── custom_button.dart             #   Button with loading state
│   │       └── custom_text_field.dart         #   Styled text input
│   └── features/
│       └── home/                              # 🏠 Sample feature (clean architecture)
│           └── presentation/
│               ├── pages/
│               │   └── home_page.dart         #   Home screen
│               ├── providers/
│               │   └── home_provider.dart     #   State management
│               └── widgets/
│                   └── home_content.dart      #   Home UI components
├── assets/
│   └── l10n/
│       ├── en.arb                             # 🌍 English translations
│       └── hi.arb                             #   Hindi translations
├── test/
│   ├── widget_test.dart                       # 🧪 Sample widget test
│   ├── core/
│   │   └── utils/
│   │       └── validators_test.dart           #   Validator unit tests
│   └── helpers/
│       └── test_helpers.dart                  #   Test utilities
├── .env.example                               # 🔐 Environment variables template
├── blueprint.yaml                             # 📘 Project metadata
└── pubspec.yaml                               # 📦 Dependencies

File Count by Feature Set:

• Minimal (no optional features): 19 files
• Full Stack (all features enabled): 43 files 🚀

🧠 Architecture Principles #

Clean Separation of Concerns #

• core/: Shared infrastructure (config, theme, routing, API)
• features/: Business logic organized by feature
• app/: Root app configuration and providers

Dependency Injection Ready #

Uses Provider for service location:

Provider<AppConfig>(create: (_) => AppConfig.load()),
Provider<ApiClient>(create: (context) => ApiClient(context.read<AppConfig>())),

Type-Safe Configuration #

class AppConfig {
  final String appTitle;
  final String environment;
  final String apiBaseUrl;
  // ...
}

🛠️ CLI Commands #

init - Create New Project #

flutter_blueprint init <app_name> [options]

Options:

add feature - Incremental feature generation (killer feature) #

Add a new feature to an existing project without touching the rest of your app. The command scaffolds clean-architecture folders (data/domain/presentation), generates state-management boilerplate that matches the project's blueprint.yaml (Provider, Riverpod or BLoC), and injects a new route into app_router.dart.

Usage:

# Full feature with all layers
flutter_blueprint add feature <feature_name>

# Only presentation layer
flutter_blueprint add feature settings --presentation --no-data --no-domain

# Add feature with remote API integration
flutter_blueprint add feature products --api

Flags:

Behavior & notes:

• The command must be run from the root of a previously generated flutter_blueprint project (it reads blueprint.yaml).
• It detects the project's state-management setting from blueprint.yaml and emits matching files for Provider, Riverpod, or Bloc.
• If app_router.dart exists, the generator will add the page import, a route constant to RouteNames, and a case in the router switch to return the new page.
• The generator is idempotent for route insertion: it will not duplicate imports or constants if they already exist.
• For Riverpod/Bloc the generated state files follow the project's Dart version (uses sealed classes / StateNotifier / Bloc patterns as appropriate).

Examples:

# Generate a full "auth" feature using the project's state-management
flutter_blueprint add feature auth

# Generate only presentation for "settings"
flutter_blueprint add feature settings --presentation --no-data --no-domain

# Generate products feature and include remote API data source
flutter_blueprint add feature products --api

📋 blueprint.yaml #

Every generated project includes a blueprint.yaml manifest:

version: 1
app_name: my_app
platform: mobile
state_management: provider
features:
  api: true
  env: true
  localization: false
  tests: true
  theme: true

Future Use: This enables regeneration, upgrades, and feature addition.

🎯 Target Audience #

• Junior developers: who don't yet know how to structure a real project
• Indie devs: who want to spin up production-ready apps quickly
• Small teams: who want standardization without heavy frameworks

🚧 Roadmap #

Phase 1: MVP ✅ (Current) #

• ✅ CLI tool setup
• ✅ Basic project generator
• ✅ Provider template
• ✅ Theme + routing boilerplate

Phase 2: Multi-Template Support #

• ❌ Riverpod template
• ❌ Bloc template
• ❌ Localization integration
• ❌ API client scaffolding

Phase 3: Feature Generation #

• ❌ flutter_blueprint add feature <name>
• ❌ Interactive upgrades via blueprint.yaml
• ❌ Unit + widget test templates

Phase 4: Advanced Features #

• ❌ Plugin ecosystem (auth, firebase, analytics)
• ❌ GitHub Actions CI scaffold
• ❌ Web/desktop platform support
• ❌ Blueprint dashboard (web-based config UI)

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide first.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support #

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🌟 Show Your Support #

If this project helped you, please ⭐ the repository and share it with others!

Made with ❤️ for the Flutter community