Building and Running

Instructions for building, running, and deploying the BookWish Flutter app across all platforms.

Prerequisites

Required Tools

• Flutter SDK: 3.0.0 or higher
• Dart SDK: Included with Flutter
• Xcode: 14.0+ (for iOS development)
• Android Studio: Latest version (for Android development)
• CocoaPods: Latest version (for iOS dependencies)

Verify Installation

flutter doctor -v

Ensure all required dependencies show checkmarks.

Project Setup

Clone and Install

# Navigate to app directory
cd /path/to/bookwish_monorepo/app

# Get Flutter dependencies
flutter pub get

# Generate code (Riverpod providers)
flutter pub run build_runner build --delete-conflicting-outputs

Firebase Configuration

1. Place google-services.json in /android/app/
2. Place GoogleService-Info.plist in /ios/Runner/
3. Ensure firebase_options.dart is generated

Environment Configuration

Create .env file in app root (not committed to git):

API_BASE_URL=https://api.bookwish.app
STRIPE_PUBLISHABLE_KEY=pk_live_...
REVENUECAT_API_KEY=...

Development

Run in Debug Mode

iOS Simulator:

flutter run -d iOS
# or target specific simulator
flutter run -d 'iPhone 15 Pro'

Android Emulator:

flutter run -d android
# or target specific emulator
flutter run -d emulator-5554

Physical Device:

# List devices
flutter devices

# Run on connected device
flutter run -d <device-id>

Web:

flutter run -d chrome
# or
flutter run -d web-server --web-port=8080

Hot Reload

During development, use hot reload for quick iterations:

• Press r in terminal to hot reload
• Press R to hot restart
• Press q to quit

Code Generation Watch Mode

For continuous code generation during development:

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

This watches for changes and regenerates Riverpod providers automatically.

Building for Release

iOS

Prerequisites

1. Apple Developer Account: Required for distribution
2. Certificates: Developer and Distribution certificates
3. Provisioning Profiles: Development and App Store profiles
4. App Store Connect: App created with bundle ID

Build Commands

Build IPA for App Store:

flutter build ipa --release

Output: build/ios/ipa/bookwish.ipa

Build for specific configuration:

flutter build ipa --release --export-options-plist=ios/ExportOptions.plist

Build without codesigning (for testing):

flutter build ios --release --no-codesign

Archive and Upload

# Build and archive
flutter build ipa --release

# Upload to App Store Connect using Xcode or Transporter app
open build/ios/ipa/

Or use Xcode:

open ios/Runner.xcworkspace
# Product → Archive → Distribute App

TestFlight Distribution

1. Build IPA with App Store configuration
2. Upload to App Store Connect
3. Submit for TestFlight review
4. Add testers in App Store Connect

Android

Prerequisites

1. Google Play Console: Account and app created
2. Signing Key: Android keystore file
3. Key Properties: Store credentials securely

Configure Signing

Create android/key.properties:

storePassword=<store-password>
keyPassword=<key-password>
keyAlias=bookwish
storeFile=<path-to-keystore>

Never commit this file to version control!

Build Commands

Build APK (for testing):

flutter build apk --release

Output: build/app/outputs/flutter-apk/app-release.apk

Build App Bundle (for Play Store):

flutter build appbundle --release

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

Build for specific ABI:

flutter build apk --split-per-abi --release

Outputs separate APKs for arm64-v8a, armeabi-v7a, x86_64.

Deploy to Play Store

1. Build app bundle:

   flutter build appbundle --release

2. Upload to Play Console:

   • Navigate to Release → Production
   • Upload app-release.aab
   • Complete release details
   • Submit for review

Internal Testing

1. Build and upload to Play Console
2. Create internal testing track
3. Add test users
4. Share test link

Web

Note: Web support is limited to landing page only. Full app is mobile-only.

Build for Production

flutter build web --release --web-renderer canvaskit

Output: build/web/

Deploy Options

Firebase Hosting:

flutter build web --release
firebase deploy --only hosting

Static Hosting (Netlify, Vercel):

flutter build web --release
# Deploy build/web directory

Configure base href:

flutter build web --base-href /subpath/ --release

Build Variants

Debug Build

# iOS
flutter build ios --debug

# Android
flutter build apk --debug

Profile Build

For performance profiling:

# iOS
flutter build ios --profile

# Android
flutter build apk --profile

Release Build

Optimized production build:

# iOS
flutter build ipa --release

# Android
flutter build appbundle --release

Platform-Specific Configuration

iOS Build Settings

In ios/Runner.xcconfig:

FLUTTER_TARGET=lib/main.dart
DEVELOPMENT_TEAM=YOUR_TEAM_ID
PRODUCT_BUNDLE_IDENTIFIER=com.bookwish.app

Android Build Configuration

In android/app/build.gradle.kts:

android {
    compileSdk = 34

    defaultConfig {
        applicationId = "com.bookwish.app"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "3.1.0"
    }
}

Version Management

Update version in pubspec.yaml:

version: 3.1.0+1
#        ↑     ↑
#        |     build number (Android versionCode, iOS CFBundleVersion)
#        version name (user-facing)

Increment for:

• Major (3.x.x): Breaking changes
• Minor (x.1.x): New features
• Patch (x.x.1): Bug fixes
• Build (+x): Internal builds

Build Optimization

Reduce Size

# Split by ABI (Android)
flutter build apk --split-per-abi --release

# Tree shaking (iOS/Android)
flutter build <platform> --release --split-debug-info=./symbols --obfuscate

Analyze Build

Size analysis:

flutter build apk --analyze-size --release
flutter build ios --analyze-size --release

Bundle analysis:

flutter build appbundle --analyze-size --release

Continuous Integration

GitHub Actions Example

name: Build and Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'
      - run: flutter pub get
      - run: flutter pub run build_runner build --delete-conflicting-outputs
      - run: flutter test
      - run: flutter build ipa --release

  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'
      - run: flutter pub get
      - run: flutter pub run build_runner build --delete-conflicting-outputs
      - run: flutter test
      - run: flutter build appbundle --release

Troubleshooting

Common Issues

"Unable to find bundled Java version":

# Update Flutter
flutter upgrade

"CocoaPods not installed":

sudo gem install cocoapods
cd ios && pod install

"Could not find build_runner":

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

Build fails with "Gradle sync failed":

cd android
./gradlew clean
cd ..
flutter clean
flutter pub get

iOS build fails with provisioning errors:

• Verify bundle ID matches provisioning profile
• Check certificate validity in Keychain
• Ensure device is registered in developer portal

Clean Build

Start fresh if builds are failing:

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

Performance Profiling

Profile Build

flutter run --profile

DevTools

flutter pub global activate devtools
flutter pub global run devtools

Then open http://localhost:9100 in browser while app is running.

Analyze Performance

flutter analyze
flutter test --coverage

Release Checklist

Before releasing to production:

• Update version in pubspec.yaml
• Run all tests: flutter test
• Check for lint issues: flutter analyze
• Generate code: flutter pub run build_runner build
• Test on physical devices (iOS and Android)
• Verify API endpoints point to production
• Update changelog
• Build release artifacts
• Test release builds on physical devices
• Upload to App Store Connect / Play Console
• Submit for review
• Monitor crash reports after release

Resources

• Flutter Documentation
• iOS Deployment Guide
• Android Deployment Guide
• App Store Connect
• Google Play Console