Flutter Flavor Manager

An advanced TypeScript-based CLI tool for managing multiple Flutter app flavors across different platforms with interactive step-by-step setup and real-time validation.

✨ Features

• 🚀 Multi-app support - Configure different apps with unique bundle IDs
• 🌍 Environment management - dev, staging, prod with different configurations
• 📱 Platform synchronization - Updates build configurations for all Flutter platforms
• 🎯 Interactive runner - CLI interface for selecting and running specific flavor combinations
• 🔀 Environment fusion - Mix configurations from different environments
• 💾 Backup/restore - Automatic backup before configuration updates
• 📦 Simple entry points - Auto-generates Dart entry points for each flavor combination
• 🎨 Advanced TUI - Beautiful terminal user interface with visual feedback
• 🧙 Interactive Setup Wizard - Step-by-step guided configuration
• 🔄 Flutter Version Management - Detect and switch between Flutter versions
• ✅ Real-time Validation - Instant feedback on configuration inputs
• 📋 Smart Detection - Automatically detects project structure and settings
• 🔷 TypeScript Powered - Full type safety and IntelliSense support
• 🏗️ Modern Architecture - Clean, modular, and maintainable codebase

💻 Requirements

• Node.js >= 16.0.0
• Flutter SDK
• TypeScript >= 4.5.0 (for development)

🚀 Installation

npm install -g flutter-flavor-manager

Or install locally in your project:

npm install flutter-flavor-manager

🎯 Quick Start

Option 1: Interactive Setup (Recommended)

flutter-flavor setup

This launches a beautiful step-by-step wizard that guides you through entire setup process with real-time validation.

Option 2: Quick Initialize

flutter-flavor init

Creates a basic configuration with sensible defaults.

Option 3: Development Mode

npm install -g flutter-flavor-manager
flutter-flavor dev  # Run in development mode with hot reload

🎮 CLI Commands

flutter-flavor setup ⭐ NEW

Run interactive setup wizard with step-by-step guidance

flutter-flavor setup

flutter-flavor init

Initialize a new flavor configuration file

flutter-flavor init [--force] [--interactive]

flutter-flavor flutter ⭐ NEW

Manage Flutter versions and channels

flutter-flavor flutter [--list] [--switch <version>] [--channel <channel>]

flutter-flavor run

Interactive runner for selecting and running flavors

flutter-flavor run [--quick]

flutter-flavor generate

Generate Dart entry points for all flavor combinations

flutter-flavor generate

flutter-flavor validate

Validate flavor configuration with real-time feedback

flutter-flavor validate

🔧 Development

Building

npm run build

Development Mode

npm run dev

Watch Mode

npm run build:watch

Testing

npm test
npm run test:watch

Linting

npm run lint
npm run lint:fix

📁 Project Structure

src/
├── types/           # TypeScript type definitions
├── core/           # Core business logic
├── tui/            # Terminal User Interface components
├── utils/          # Utility functions
└── cli.ts          # Main CLI entry point

dist/               # Compiled JavaScript output
├── cli.js          # Built CLI entry point
├── index.js        # Main library exports
└── *.d.ts          # Type declaration files

🏗️ Architecture

The TypeScript-based architecture provides:

Type Safety

• Full type coverage - All modules have complete type definitions
• IntelliSense support - Excellent IDE autocompletion
• Compile-time checking - Catch errors before runtime

Modular Design

• Separation of concerns - Clean separation between UI, core logic, and utilities
• Reusable components - Modular TUI components
• Extensible architecture - Easy to add new features

Modern Practices

• Async/await - Modern promise handling
• ES6+ features - Latest JavaScript features
• Error handling - Comprehensive error management

📚 TypeScript API

Core Classes

import { 
  FlavorController, 
  EntryPointGenerator, 
  InteractiveSetupWizard,
  FlutterVersionManager,
  RealTimeValidator,
  AdvancedTUI
} from 'flutter-flavor-manager';

// Setup wizard
const wizard = new InteractiveSetupWizard();
await wizard.run();

// Flutter version management
const flutterManager = new FlutterVersionManager();
const versions = await flutterManager.detectInstalledVersions();

// Validation
const validator = new RealTimeValidator();
const issues = await validator.validateConfiguration(config);

// TUI components
const tui = new AdvancedTUI();
tui.showHeader('My Title', 'Subtitle');
tui.showSuccessBox('Operation completed');

Type Definitions

interface FlavorConfig {
  project: ProjectInfo;
  apps: App[];
  platforms: Platform[];
  options: FlavorConfigOptions;
  version: string;
  generatedAt: string;
}

interface Environment {
  name: string;
  displayName: string;
  baseUrl: string;
  apiKey: string;
  bundleIdSuffix: string;
  versionSuffix: string;
}

interface FlutterVersion {
  version: string;
  channel: string;
  path?: string;
  date?: string;
  isCurrent: boolean;
  isActive: boolean;
}

🎨 Advanced TUI Features

The TypeScript-powered TUI provides:

• Type-safe components - All UI functions have proper types
• Consistent API - Uniform interface across all components
• Error handling - Built-in error management
• Accessibility - Screen reader compatible output

const tui = new AdvancedTUI();

// Type-safe method calls
tui.showHeader('Title', 'Subtitle');
tui.showProgressBar(5, 10, 'Processing');
tui.showSuccessBox('Operation completed');

// Type-safe tables
const table = tui.createFancyTable(
  ['Header 1', 'Header 2'],
  [['Row 1 Col 1', 'Row 1 Col 2']],
  { borderStyle: 'round' }
);

🔄 Flutter Version Management

Enhanced with type safety:

const manager = new FlutterVersionManager();

// Returns typed array
const versions: FlutterVersion[] = await manager.detectInstalledVersions();

// Type-safe operations
const success: boolean = await manager.switchVersion(versions[0]);

// Enum support for channels
enum FlutterChannel {
  STABLE = 'stable',
  BETA = 'beta',
  DEV = 'dev',
  MASTER = 'master'
}

✅ Real-time Validation

Type-safe validation with comprehensive error handling:

const validator = new RealTimeValidator();

// Type-safe field validation
const result = await validator.validateField('packageName', 'com.example.app', {
  type: 'packageName'
});

if (!result.valid) {
  console.log(`Error: ${result.message}`);
}

// Configuration validation
const issues = await validator.validateConfiguration(config);

🤝 Contributing

Development Setup

1. Clone the repository

   git clone https://github.com/digitwhale/flutter-flavor-manager.git
   cd flutter-flavor-manager

2. Install dependencies

   npm install

3. Run in development mode

   npm run dev

4. Build and test

   npm run build
   npm test
   npm run lint

Type Safety

All new code must:

• Have complete type definitions
• Use strict TypeScript settings
• Pass ESLint checks
• Include proper error handling

Adding New Features

1. Define types in src/types/index.ts
2. Implement logic in appropriate src/core/ module
3. Add TUI components if needed in src/tui/
4. Update CLI in src/cli.ts
5. Write tests in test/
6. Update documentation

📜 License

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

🙏 Acknowledgments

• TypeScript team - For the amazing language and tooling
• Node.js community - For the ecosystem and packages
• Flutter team - For the excellent cross-platform framework

Built with ❤️ and TypeScript for type safety and developer experience.