Flutter Starter Template

A comprehensive Flutter starter template with all the essential features for building production-ready applications.

Features

• 🎯 Clean Architecture - Organized with clear separation of concerns
• 🔄 State Management - Bloc pattern implementation
• 🌐 Networking - Dio with interceptors and error handling
• 🗺️ Navigation - GoRouter with guarded routes
• 💉 Dependency Injection - get_it and injectable
• 💾 Local Storage - Hive database integration
• 🔐 Authentication - Complete auth flow with login/logout
• 🎨 Theming - Light/Dark mode support
• 🏗️ Flavors - Dev, Staging, and Production environments
• 📝 Logging - Comprehensive logging system
• 🚨 Error Handling - Global error handling with custom exceptions
• 🔄 Mock Data - Works offline with mock APIs (easily switchable to real APIs)

Getting Started

Prerequisites

• Flutter SDK (3.24.0 or higher)
• Dart SDK (3.0.0 or higher)
• Android Studio / VS Code
• Git
• Node.js (for git hooks and scripts)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/flutter_starter_template.git
cd flutter_starter_template

2. Run the setup script:

npm run setup

Or manually:

flutter pub get
flutter pub run build_runner build --delete-conflicting-outputs
npm run hooks:install

On Windows, you can also use:

scripts\setup-hooks.bat

Quick Start (Demo Mode)

The app comes pre-configured with mock data so you can run it immediately:

1. Install dependencies: flutter pub get
2. Generate code: flutter pub run build_runner build --delete-conflicting-outputs
3. Run the app: flutter run --flavor dev -t lib/main_dev.dart

Demo Credentials:

• Email: demo@example.com
• Password: password123

The app will work completely offline and demonstrate all features!

Switching to Real APIs

See SETUP_GUIDE.md for detailed instructions on connecting real APIs.

Running the App

Development

flutter run --flavor dev -t lib/main_dev.dart

Staging

flutter run --flavor staging -t lib/main_staging.dart

Production

flutter run --flavor prod -t lib/main_prod.dart

Project Structure

lib/
├── config/
│   ├── env/              # Environment configurations
│   └── injection/        # Dependency injection setup
├── core/
│   ├── constants/        # App constants
│   ├── errors/           # Error handling
│   ├── network/          # API client and interceptors
│   ├── routes/           # Navigation configuration
│   ├── services/         # Core services (Hive, etc.)
│   ├── theme/            # App theming
│   └── utils/            # Utility functions
├── features/
│   ├── auth/            # Authentication feature
│   │   ├── data/        # Data layer
│   │   ├── domain/      # Domain layer
│   │   └── presentation/# Presentation layer
│   ├── home/            # Home feature
│   ├── profile/         # Profile feature
│   └── splash/          # Splash screen
├── shared/
│   ├── models/          # Shared models
│   ├── repositories/    # Shared repositories
│   ├── services/        # Shared services
│   └── widgets/         # Shared widgets
└── main_*.dart          # Entry points for different flavors

Configuration

Environment Variables

Create .env files for each environment:

• .env.dev - Development environment
• .env.staging - Staging environment
• .env.prod - Production environment

Example:

BASE_URL=https://api.example.com
API_VERSION=v1
APP_NAME=Flutter Starter
ENVIRONMENT=development
DEBUG_MODE=true

Adding New Features

1. Create feature folder structure:

features/
└── new_feature/
    ├── data/
    │   ├── datasources/
    │   ├── models/
    │   └── repositories/
    ├── domain/
    │   ├── entities/
    │   ├── repositories/
    │   └── usecases/
    └── presentation/
        ├── bloc/
        ├── pages/
        └── widgets/

2. Register dependencies in injectable classes
3. Add routes in app_router.dart
4. Run build_runner to generate code

Testing

Unit Tests

npm run test
# or
flutter test

Integration Tests

npm run test:integration
# or
flutter test integration_test/

Coverage Report

npm run test:coverage
# or
flutter test --coverage

Running Specific Tests

# Run tests for a specific file
flutter test test/unit/features/auth/domain/usecases/login_usecase_test.dart

# Run tests with specific pattern
flutter test --plain-name="login"

Building

Android

Development:

flutter build apk --flavor dev -t lib/main_dev.dart

Production:

flutter build apk --flavor prod -t lib/main_prod.dart --release

Git Hooks & Code Quality

This project includes automated git hooks for maintaining code quality:

Available Hooks

• pre-commit: Runs formatting, linting, and basic security checks
• commit-msg: Validates conventional commit message format
• prepare-commit-msg: Adds branch ticket numbers and commit templates
• pre-push: Runs tests and build checks before pushing

Hook Management

# Install hooks
npm run hooks:install

# Temporarily skip hooks
git commit --no-verify

# Uninstall hooks
npm run hooks:uninstall

Conventional Commits

This project follows Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks
• perf: Performance improvements
• ci: CI/CD changes
• build: Build system changes

Examples:

feat(auth): add biometric authentication
fix: resolve memory leak in image cache
docs: update API documentation
test: add integration tests for payment flow

CI/CD Pipeline

GitHub Actions Workflows

• CI Pipeline (.github/workflows/ci.yml):

  • Runs on every push and PR
  • Tests, linting, and builds for all flavors
  • Generates coverage reports

• CD Pipeline (.github/workflows/cd.yml):

  • Triggered on version tags (v*)
  • Builds production releases
  • Creates GitHub releases
  • Deploys to Google Play Store (if configured)

• PR Checks (.github/workflows/pr-checks.yml):

  • Code quality checks
  • Security scanning
  • Dependency vulnerability checks

Creating a Release

1. Update version in pubspec.yaml
2. Create and push a git tag:

git tag v1.0.0
git push origin v1.0.0

3. GitHub Actions will automatically build and create a release

Available Scripts

# Setup and development
npm run setup              # Complete project setup
npm run clean              # Clean and reinstall dependencies
npm run generate           # Generate code with build_runner

# Running the app
npm run run:dev            # Run development flavor
npm run run:staging        # Run staging flavor  
npm run run:prod           # Run production flavor

# Building
npm run build:dev          # Build development APK
npm run build:staging      # Build staging APK
npm run build:prod         # Build production APK

# Testing and quality
npm run test               # Run unit tests
npm run test:coverage      # Run tests with coverage
npm run test:integration   # Run integration tests
npm run analyze            # Run Flutter analyze
npm run format             # Format code
npm run format:check       # Check code formatting
npm run lint               # Run linting checks
npm run pre-commit         # Run pre-commit checks manually

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some 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.