flutter-core:flutter-deployment

What this skill does

# Flutter Deployment

## Description

Comprehensive guide for deploying Flutter applications to all platforms including mobile (Android, iOS), web, and desktop (Windows, macOS, Linux). Covers build configuration, code signing, app store submission, CI/CD automation, and production best practices.

## When to Use

Use this skill when:

- Preparing Flutter apps for release to production
- Configuring build flavors for different environments (dev, staging, production)
- Setting up code signing and certificates for iOS/Android
- Submitting apps to Google Play Store, Apple App Store, or Microsoft Store
- Deploying web apps with PWA capabilities
- Distributing desktop applications
- Implementing CI/CD pipelines with GitHub Actions, Codemagic, or fastlane
- Troubleshooting deployment issues or build failures
- Optimizing release builds for size and performance
- Managing version numbers and release cycles

## Core Deployment Concepts

### Build Modes

Flutter supports three compilation modes optimized for different stages:

**Debug Mode** - Active development with hot reload
- Assertions enabled for runtime validation
- Service extensions enabled (DevTools)
- Fast compilation, slower execution
- Default mode for `flutter run`
- Only mode supported on emulators/simulators

**Profile Mode** - Performance analysis
- Some debugging capabilities maintained
- Service extensions enabled for profiling
- Performance closer to release mode
- DevTools can connect for analysis
- Not supported on emulators/simulators

**Release Mode** - Production deployment
- Assertions disabled
- Debugging stripped
- Optimized for fast startup and small size
- Service extensions disabled
- Required for app store submission

```bash
flutter run                    # debug mode
flutter run --profile         # profile mode
flutter run --release         # release mode
flutter build <target>        # builds in release mode
```

### Platform Build Targets

Each platform has specific build commands and outputs:

```bash
# Mobile
flutter build apk             # Android APK
flutter build appbundle       # Android App Bundle (preferred)
flutter build ipa             # iOS App Store package

# Web
flutter build web             # Static web files

# Desktop
flutter build windows         # Windows executable
flutter build macos           # macOS application bundle
flutter build linux           # Linux executable
```

### Version Management

Version numbers follow semantic versioning with build numbers:

```yaml
# pubspec.yaml
version: 1.2.3+45
```

Format: `MAJOR.MINOR.PATCH+BUILD_NUMBER`

Override during build:
```bash
flutter build appbundle --build-name=1.2.3 --build-number=45
```

**Platform-specific considerations:**
- **Android:** `versionCode` must be unique integer for each upload
- **iOS:** Build number must be unique for each TestFlight/App Store upload
- **Windows:** Last revision number must be 0 (e.g., 1.2.3.0)

### Code Obfuscation

Protect Dart code by obscuring function and class names:

```bash
flutter build appbundle \
  --obfuscate \
  --split-debug-info=out/android
```

**Important notes:**
- Only works on release builds
- Save symbol files for crash report de-obfuscation
- May break reflection-based code
- Not supported for web (uses minification instead)

Use `flutter symbolize` to decode obfuscated stack traces:

```bash
flutter symbolize -i stack_trace.txt -d out/android
```

## Platform-Specific Deployment

### Android Deployment

**Prerequisites:**
- Google Play Developer account ($25 one-time fee)
- Upload keystore for app signing
- Configured `build.gradle` files

**Key steps:**
1. Create and configure signing keystore
2. Reference keystore in `key.properties`
3. Configure Gradle signing in `build.gradle.kts`
4. Build app bundle (preferred) or APK
5. Upload to Play Console
6. Complete store listing
7. Submit for review

**Recommended build:**
```bash
flutter build appbundle --release
```

Output: `build/app/outputs/bundle/release/app.aab`

### iOS Deployment

**Prerequisites:**
- Apple Developer Program membership ($99/year)
- Mac with Xcode installed
- Registered Bundle ID
- Code signing certificates and provisioning profiles

**Key steps:**
1. Register Bundle ID on Apple Developer portal
2. Create app record in App Store Connect
3. Configure Xcode project settings (signing, bundle ID)
4. Build release archive
5. Upload to App Store Connect
6. Optional: TestFlight beta testing
7. Submit for App Store review

**Build command:**
```bash
flutter build ipa --release
```

Output: `build/ios/ipa/*.ipa`

### Web Deployment

**Build command:**
```bash
flutter build web --release
```

Output: `build/web/` directory with static files

**Hosting options:**
- Firebase Hosting (recommended for Flutter)
- GitHub Pages
- Netlify
- Vercel
- Any static web hosting service

**PWA configuration:**
- Edit `web/manifest.json` for app metadata
- Customize `flutter_service_worker.js` for caching
- Serve over HTTPS (required for service workers)

### Desktop Deployment

**Windows:**
- Build MSIX package for Microsoft Store
- Or distribute standalone `.exe`
- Use `msix` pub package for packaging

```bash
flutter build windows --release
```

**macOS:**
- Submit to Mac App Store via App Store Connect
- Or notarize for distribution outside store
- Requires Apple Developer membership

```bash
flutter build macos --release
```

**Linux:**
- Snap Store (recommended)
- AppImage, deb, flatpak (via community tools)
- Requires snapcraft configuration

```bash
flutter build linux --release
```

## Build Flavors

Build flavors allow different configurations for development, staging, and production:

**Benefits:**
- Different app names and icons
- Separate API endpoints
- Environment-specific feature flags
- Multiple versions installed simultaneously

**Android configuration:**

```kotlin
// android/app/build.gradle.kts
android {
    flavorDimensions += "default"
    productFlavors {
        create("dev") {
            dimension = "default"
            applicationIdSuffix = ".dev"
            resValue("string", "app_name", "MyApp Dev")
        }
        create("staging") {
            dimension = "default"
            applicationIdSuffix = ".staging"
            resValue("string", "app_name", "MyApp Staging")
        }
        create("prod") {
            dimension = "default"
            resValue("string", "app_name", "MyApp")
        }
    }
}
```

**iOS configuration:**

Create schemes in Xcode for each flavor with different configurations and build settings.

**Running flavors:**
```bash
flutter run --flavor dev
flutter build appbundle --flavor prod
```

## CI/CD Integration

### GitHub Actions

Create `.github/workflows/deploy.yml`:

```yaml
name: Deploy Flutter App

on:
  push:
    branches: [ main ]

jobs:
  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.38.6'
      - run: flutter pub get
      - run: flutter test
      - run: flutter build appbundle --release
      - name: Upload to Play Store
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.SERVICE_ACCOUNT_JSON }}
          packageName: com.example.app
          releaseFiles: build/app/outputs/bundle/release/app.aab
          track: internal
```

### Codemagic

Configure via `codemagic.yaml` or web UI:

```yaml
workflows:
  ios-workflow:
    name: iOS Workflow
    environment:
      flutter: stable
      xcode: latest
    scripts:
      - flutter pub get
      - flutter test
      - flutter build ipa --release
    artifacts:
      - build/ios/ipa/*.ipa
    publishing:
      app_store_connect:
        api_key: $APP_STORE_CONNECT_PRIVATE_KEY
        submit_to_testflight: true
```

### fastlane

Install in both `android/` and `ios/` directories:

```bash
cd android && fastlane init
cd ios && fastlane init
```

**Android Fastfile:**
```ruby
lane :deploy do
  gradle(ta