🚀 Flutter Starter

A production-ready Flutter starter project with Clean Architecture, enterprise-grade configuration management, and comprehensive developer tooling.

✨ Features

🏗️ Architecture & Code Quality

✅ Clean Architecture - Separation of concerns with Domain, Data, and Presentation layers
✅ State Management - Riverpod for reactive state management
✅ Code Generation - Freezed for immutable classes and JSON serialization
✅ Linting - Very Good Analysis for comprehensive code quality checks
✅ Testing - Mocktail for unit testing with comprehensive test coverage

⚙️ Configuration & Environment

✅ Multi-Environment Support - Development, Staging, Production
✅ Flexible Configuration - .env files for local dev, --dart-define for CI/CD
✅ Feature Flags - Local and remote (Firebase Remote Config) feature flags
✅ Environment-Aware Defaults - Smart defaults based on environment
✅ Type-Safe Configuration - Typed getters with fallback chain

🌐 Internationalization

✅ Multi-Language Support - Flutter localization with ARB files
✅ RTL Support - Right-to-left language support
✅ Locale Persistence - Save and restore user language preference

🔐 Security & Storage

✅ Secure Storage - Flutter Secure Storage for sensitive data
✅ Shared Preferences - Simple key-value storage for non-sensitive data
✅ Storage Migration - Version-based storage migration system
✅ Error Handling - Comprehensive error handling with custom exceptions

🌐 Network Layer

✅ HTTP Client - Dio with interceptors support
✅ Configurable Timeouts - Environment-based timeout configuration
✅ Request/Response Logging - Debug-friendly HTTP logging
✅ Error Interceptors - Automatic error handling and conversion
✅ Auth Interceptors - Automatic token injection and refresh

🎨 UI & UX

✅ Material Design - Material 3 theme support
✅ Dark Mode - Built-in dark theme support
✅ Accessibility - Semantic labels and accessibility support
✅ Responsive Design - Adaptive layouts for different screen sizes

🧭 Routing & Navigation

✅ Type-Safe Routing - GoRouter with type-safe route definitions
✅ Deep Linking - Support for deep links and URL navigation
✅ Auth-Based Routing - Protected routes with authentication redirects
✅ Navigation Logging - Automatic route tracking and logging

📊 Logging & Monitoring

✅ Comprehensive Logging - Multi-level logging with file and console output
✅ Log Rotation - Automatic log file rotation
✅ Structured Logging - JSON formatting for production
✅ Performance Monitoring - Firebase Performance integration
✅ Screen Tracking - Automatic screen load time tracking

🚀 Deployment & CI/CD

✅ Multi-Platform - Android, iOS, Web, Linux, macOS, Windows support
✅ CI/CD Ready - GitHub Actions workflows included (disabled by default, uncomment triggers to enable)
✅ Version Management - Automated version bumping scripts
✅ Fastlane Integration - iOS and Android deployment automation

📚 Documentation

✅ Comprehensive Docs - Architecture, guides, API documentation
✅ Migration Guides - From MVC, GetX, Bloc, and other architectures
✅ Best Practices - Code examples and patterns
✅ API Documentation - Complete API reference
✅ Example Features - 3 complete example features (Auth, Feature Flags, Tasks)

🧪 Testing

✅ 66 Test Files - Comprehensive test coverage
✅ Unit Tests - Domain and data layer testing
✅ Widget Tests - UI component testing
✅ Integration Tests - End-to-end flow testing
✅ Test Helpers - Reusable test utilities and fixtures

🛠️ Tech Stack

Core Dependencies

Flutter - UI framework
Riverpod - State management
Dio - HTTP client
Freezed - Code generation for immutable classes
Equatable - Value equality comparison

Firebase

Firebase Core - Firebase initialization
Firebase Remote Config - Remote feature flags
Firebase Performance - Performance monitoring and tracking

Storage

flutter_secure_storage - Secure storage for sensitive data
shared_preferences - Simple key-value storage

Localization

flutter_localizations - Flutter localization support
intl - Internationalization utilities

Routing & Navigation

go_router - Declarative routing with deep linking

Logging & Monitoring

logger - Comprehensive logging solution
path_provider - File system access for log files

Development Tools

build_runner - Code generation runner
very_good_analysis - Linting rules
mocktail - Testing and mocking

📁 Project Structure

lib/
├── core/                    # Core infrastructure
│   ├── config/             # Configuration system
│   ├── constants/          # App constants
│   ├── di/                 # Dependency injection (Riverpod providers)
│   ├── errors/             # Error handling
│   ├── feature_flags/      # Feature flags infrastructure
│   ├── localization/       # Localization service
│   ├── logging/            # Logging service
│   ├── network/            # Network layer (Dio setup)
│   ├── performance/        # Performance monitoring
│   ├── routing/            # Routing system (go_router)
│   ├── storage/            # Storage services (with migration)
│   └── utils/              # Utility functions
│
├── features/                # Feature modules (Clean Architecture)
│   ├── auth/               # Authentication feature example
│   │   ├── data/          # Data layer (models, data sources, repositories)
│   │   ├── domain/        # Domain layer (entities, use cases, repository interfaces)
│   │   └── presentation/  # Presentation layer (screens, widgets, providers)
│   ├── feature_flags/      # Feature flags feature
│   │   └── presentation/   # Feature flags UI
│   └── tasks/              # Tasks feature (CRUD example)
│       ├── data/          # Data layer
│       ├── domain/        # Domain layer
│       └── presentation/  # Presentation layer
│
├── shared/                  # Shared resources
│   ├── accessibility/      # Accessibility utilities
│   ├── extensions/         # Dart extensions
│   ├── theme/              # App theme configuration
│   └── widgets/            # Reusable widgets
│
├── l10n/                   # Localization files (generated)
└── main.dart               # App entry point

🚀 Getting Started

Prerequisites

Flutter SDK (>=3.0.0)
Dart SDK (>=3.0.0)
Android Studio / VS Code with Flutter extensions
Xcode (for iOS development on macOS)

Installation

Create repository from template (if using GitHub template)
- Click "Use this template" button on GitHub
- Create a new repository from this template
- Clone your new repository:
```
git clone <your-repository-url>
cd <your-project-name>
```
OR clone directly (if not using template):
```
git clone <repository-url>
cd flutter_starter
```
Install dependencies
```
flutter pub get
```

Generate code (Freezed, JSON serialization)

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

Set up environment configuration

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration
# See Configuration System section below

Set up Git hooks (optional but recommended)
```
./scripts/setup-git-hooks.sh
```
This will install Git hooks for:
- Code formatting checks (pre-commit)
- Commit message validation (commit-msg)
- Test execution (pre-push)
Run the app
```
flutter run
```

First Steps

Rename the project (if needed) - Update package name from flutter_starter to your project name
Configure your environment - See Configuration System below
Set up Firebase (optional) - For remote feature flags and performance monitoring
- Add google-services.json (Android) and GoogleService-Info.plist (iOS)
- Initialize Firebase in your app
Customize the theme - Edit lib/shared/theme/app_theme.dart
Explore example features - Check out lib/features/ for examples:
- Auth - Authentication flow example
- Feature Flags - Feature flags UI example
- Tasks - Complete CRUD example with local storage
Add your first feature - Follow the pattern in example features
Read the documentation - Check out docs/ folder for detailed guides

⚙️ Configuration System

This project includes a production-ready, multi-environment configuration system that supports:

Local Development: .env files for easy local configuration
CI/CD: --dart-define flags for build-time configuration
Fallback Chain: .env → --dart-define → defaults
Environment-Aware Defaults: Different configurations per environment
Feature Flags: Enable/disable features per environment
Network Configuration: Timeout settings for API calls
Debug Utilities: Tools for inspecting configuration

Architecture

The configuration system consists of two main classes:

EnvConfig (lib/core/config/env_config.dart): Low-level environment variable loader
- Loads from .env files using flutter_dotenv
- Reads from --dart-define flags
- Provides fallback chain: .env → --dart-define → defaults
AppConfig (lib/core/config/app_config.dart): High-level application configuration
- Uses EnvConfig to get values
- Provides typed getters (String, bool, int)
- Environment-aware defaults
- Feature flags
- Network timeout configuration
- Debug utilities

Setup

1. Create `.env` file for local development

# Copy the example file
cp .env.example .env

# Edit .env with your values
# The .env file is gitignored and won't be committed

2. Configure your environment variables

Edit .env with your configuration:

ENVIRONMENT=development
BASE_URL=http://localhost:3000
ENABLE_LOGGING=true
ENABLE_ANALYTICS=false

Usage Examples

Local Development (using `.env` file)

Create .env file from .env.example
Fill in your values
Run the app normally:

flutter run

The app will automatically load values from .env.

Staging Build (using `--dart-define`)

For CI/CD or when you don't want to use .env files:

flutter run \
  --dart-define=ENVIRONMENT=staging \
  --dart-define=BASE_URL=https://api-staging.example.com \
  --dart-define=ENABLE_ANALYTICS=true

Production Build (using `--dart-define`)

flutter build apk \
  --dart-define=ENVIRONMENT=production \
  --dart-define=BASE_URL=https://api.example.com \
  --dart-define=ENABLE_ANALYTICS=true \
  --dart-define=ENABLE_CRASH_REPORTING=true

Using Configuration in Code

Basic Usage

import 'package:flutter_starter/core/config/app_config.dart';

// Get environment
final env = AppConfig.environment; // 'development', 'staging', or 'production'

// Check environment
if (AppConfig.isDevelopment) {
  // Development-specific code
}

// Get API base URL
final baseUrl = AppConfig.baseUrl;

// Check feature flags
if (AppConfig.enableLogging) {
  logger.info('App started');
}

if (AppConfig.enableAnalytics) {
  analytics.trackEvent('app_opened');
}

Network Configuration

import 'package:flutter_starter/core/config/app_config.dart';
import 'package:dio/dio.dart';

final dio = Dio(
  BaseOptions(
    baseUrl: AppConfig.baseUrl,
    connectTimeout: Duration(seconds: AppConfig.apiConnectTimeout),
    receiveTimeout: Duration(seconds: AppConfig.apiReceiveTimeout),
    sendTimeout: Duration(seconds: AppConfig.apiSendTimeout),
  ),
);

Debug Utilities

import 'package:flutter_starter/core/config/app_config.dart';

// Print configuration to console (only in debug mode)
AppConfig.printConfig();

// Get configuration as a map
final config = AppConfig.getDebugInfo();
print(config);

Available Configuration Options

Environment Variables

Variable	Type	Default	Description
`ENVIRONMENT`	String	`development`	Environment name: `development`, `staging`, or `production`
`BASE_URL`	String	Environment-aware	API base URL (see defaults below)
`API_TIMEOUT`	int	`30`	API timeout in seconds
`API_CONNECT_TIMEOUT`	int	`10`	API connect timeout in seconds
`API_RECEIVE_TIMEOUT`	int	`30`	API receive timeout in seconds
`API_SEND_TIMEOUT`	int	`30`	API send timeout in seconds
`ENABLE_LOGGING`	bool	Environment-aware	Enable logging (default: true in dev/staging)
`ENABLE_ANALYTICS`	bool	Environment-aware	Enable analytics (default: true in staging/prod)
`ENABLE_CRASH_REPORTING`	bool	Environment-aware	Enable crash reporting (default: true in staging/prod)
`ENABLE_PERFORMANCE_MONITORING`	bool	Environment-aware	Enable performance monitoring (default: true in staging/prod)
`ENABLE_DEBUG_FEATURES`	bool	Environment-aware	Enable debug features (default: true in dev)
`ENABLE_HTTP_LOGGING`	bool	Environment-aware	Enable HTTP request/response logging (default: true in dev)
`APP_VERSION`	String	`1.0.0`	App version
`APP_BUILD_NUMBER`	String	`1`	App build number

Environment-Aware Defaults

BASE_URL defaults:

Development: http://localhost:3000
Staging: https://api-staging.example.com
Production: https://api.example.com

Feature Flag defaults:

Logging: Enabled in development and staging
Analytics: Enabled in staging and production
Crash Reporting: Enabled in staging and production
Performance Monitoring: Enabled in staging and production
Debug Features: Enabled in development only
HTTP Logging: Enabled in development only

Best Practices

Never commit .env files: They contain sensitive information and are gitignored
Use .env.example as a template: Commit this file with placeholder values
Use .env for local development: Easy to change values without rebuilding
Use --dart-define for CI/CD: More secure and doesn't require file management
Set environment-specific defaults: Let the system handle defaults based on environment
Use feature flags: Enable/disable features per environment without code changes

Troubleshooting

Configuration not loading

Ensure EnvConfig.load() is called in main() before runApp()
Check that .env file exists in the project root
Verify pubspec.yaml includes .env in assets
Run flutter pub get after adding flutter_dotenv

Values not updating

Hot reload doesn't reload environment variables - do a full restart
For --dart-define values, rebuild the app
Check that you're using the correct variable name (case-sensitive)

Debug configuration

Use AppConfig.printConfig() in debug mode to see all configuration values:

if (AppConfig.isDebugMode) {
  AppConfig.printConfig();
}

This will print all configuration values to the console, helping you verify what values are being used.

🧪 Testing

Run Tests

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/features/auth/domain/usecases/login_test.dart

Test Structure

Tests follow the same structure as the source code:

66 test files with comprehensive coverage
Unit tests for use cases and utilities
Widget tests for UI components
Integration tests for end-to-end flows
Test helpers and fixtures for reusable test utilities

Test Coverage

The project includes:

✅ Domain layer tests (use cases, entities)
✅ Data layer tests (repositories, data sources, models)
✅ Presentation layer tests (screens, widgets, providers)
✅ Core infrastructure tests (config, network, storage, logging, performance)
✅ Integration tests for complete flows

🏗️ Building

Android

# Debug APK
flutter build apk --debug

# Release APK
flutter build apk --release

# App Bundle (for Play Store)
flutter build appbundle --release

iOS

# Debug
flutter build ios --debug

# Release
flutter build ios --release

Web

# Debug
flutter build web --debug

# Release
flutter build web --release

📚 Documentation

Architecture

Architecture Documentation - Complete architecture documentation index
Architecture Overview - Why Clean Architecture, benefits, trade-offs, and learning resources
Design Decisions - Detailed rationale for routing, state management, error handling, logging, storage, and HTTP client choices

Guides

Getting Started - Step-by-step setup guide
Understanding the Codebase - Architecture and patterns
Common Tasks - Frequently performed tasks
Routing Guide - GoRouter navigation and deep linking
Git Hooks Setup - Setup Git hooks for code quality (similar to Husky)
Adding Features - How to add new features

Migration Guides

Features

Feature Flags - Feature flags system documentation
Tasks Feature - CRUD example feature documentation
Localization - i18n setup and usage
Logging - Logging system documentation
Performance - Performance monitoring guides
Routing - Routing and navigation guide

Deployment

Deployment Guide - Complete deployment documentation
Quick Start - Get started in 5 minutes
Android Deployment - Android-specific guide
iOS Deployment - iOS-specific guide
Web Deployment - Web-specific guide
Release Process - Version management and releases
Monitoring & Analytics - Crashlytics and analytics setup

API Documentation

API Overview - API documentation index
Examples - Code examples and patterns

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

How to report bugs
How to suggest enhancements
Development setup and workflow
Coding standards and guidelines
Testing requirements
Commit message conventions

Quick Start

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes following our coding standards
Write or update tests
Commit your changes using conventional commits
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

For detailed guidelines, please read CONTRIBUTING.md.

📝 License

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

🙏 Acknowledgments

Flutter - The framework
Riverpod - State management
Very Good Ventures - Linting rules and best practices
Freezed - Code generation

📞 Support

For questions, issues, or contributions, please open an issue on GitHub.

Made with ❤️ using Flutter

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.github/workflows		.github/workflows
.vscode		.vscode
android		android
assets		assets
docs		docs
fastlane		fastlane
ios		ios
lib		lib
linux		linux
macos		macos
scripts		scripts
test		test
web		web
windows		windows
.env.example		.env.example
.gitignore		.gitignore
.metadata		.metadata
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
analysis_options.yaml		analysis_options.yaml
codecov.yml		codecov.yml
l10n.yaml		l10n.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

License

koniz-dev/flutter-starter

Folders and files

Latest commit

History

Repository files navigation

🚀 Flutter Starter

✨ Features

🏗️ Architecture & Code Quality

⚙️ Configuration & Environment

🌐 Internationalization

🔐 Security & Storage

🌐 Network Layer

🎨 UI & UX

🧭 Routing & Navigation

📊 Logging & Monitoring

🚀 Deployment & CI/CD

📚 Documentation

🧪 Testing

🛠️ Tech Stack

Core Dependencies

Firebase

Storage

Localization

Routing & Navigation

Logging & Monitoring

Development Tools

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

First Steps

⚙️ Configuration System

Architecture

Setup

1. Create .env file for local development

2. Configure your environment variables

Usage Examples

Local Development (using .env file)

Staging Build (using --dart-define)

Production Build (using --dart-define)

Using Configuration in Code

Basic Usage

Network Configuration

Debug Utilities

Available Configuration Options

Environment Variables

Environment-Aware Defaults

Best Practices

Troubleshooting

Configuration not loading

Values not updating

Debug configuration

🧪 Testing

Run Tests

Test Structure

Test Coverage

🏗️ Building

Android

iOS

Web

📚 Documentation

Architecture

Guides

Migration Guides

Features

Deployment

API Documentation

🤝 Contributing

Quick Start

📝 License

🙏 Acknowledgments

📞 Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

1. Create `.env` file for local development

Local Development (using `.env` file)

Staging Build (using `--dart-define`)

Production Build (using `--dart-define`)

Packages