Setup Variants Skill

This skill configures dev, stg, and prd build variants for both Android and iOS in a standard Flutter project.

Reference Guide: Setup Development Environments Guide

Prerequisites

• A standard Flutter project structure
• secureFiles directory with signing keys and flavor configurations (json)

Steps

1. Android Setup

1. Modify android/app/build.gradle.kts:

- Apply the flavor and signing configuration. - Use the template from local resources: .agent/skills/setupvariants/resources/android/buildgradle_flavors.kts. - Ensure signingConfigs map to secureFiles correctly.

1. Update .gitignore:

- Add keystore.properties to android/.gitignore (defensive, in case it is copied locally).

1. Verify Android Build:

- Run ./gradlew bundleRelease (or assembleRelease) to ensure gradle syncs and builds correctly.

2. iOS Setup

The iOS config lives in ios/Runner.xcodeproj/project.pbxproj (build configurations), ios/Runner.xcodeproj/xcshareddata/xcschemes/ (schemes), and ios/Flutter/*.xcconfig. One idempotent script does the pbxproj + xcconfig work; the schemes and Info.plist are edited once by hand.

1. Copy scripts to ios/scripts/ and chmod +x the shell one:

- setupiosflavors.py (pbxproj build configs + per-flavor xcconfigs + the GoogleService build phase) - copygoogleserviceplist.sh > Do not reintroduce extractdartdefines.sh / updateproject.py - a build-time > extraction script runs after Flutter probes the bundle id, so flutter run targets a > stale id; and update_project.py was not idempotent (re-runs duplicated every config).

1. Reset a mangled project.pbxproj first (only if it was previously processed).

setupiosflavors.py expects a stock Flutter pbxproj. If flavor configs already exist (possibly duplicated), restore the pristine file from git history, e.g. git checkout <first-commit> -- ios/Runner.xcodeproj/project.pbxproj, then re-run below. Flutter re-adds its SPM package reference automatically on the next build; pod install re-adds the CocoaPods phases.

1. Run (from the repo root): python3 ios/scripts/setupiosflavors.py

For each {Debug,Release,Profile}-{dev,stg,prd} it adds a build configuration to the Project / Runner / RunnerTests lists, sets the Runner config's PRODUCTBUNDLEIDENTIFIER to <base id><APPIDSUFFIX> (read from secureFiles/<flavor>/environment-configs.json), points its base xcconfig at Flutter/<Mode>-<flavor>.xcconfig, and adds a "Copy GoogleService-Info.plist" build phase after Resources. It also (re)writes Flutter/<Mode>-<flavor>.xcconfig with the Pods include, Generated.xcconfig, and DARTDEFINESAPP_NAME from the JSON. Safe to re-run. Validate: plutil -lint ios/Runner.xcodeproj/project.pbxproj.

1. ios/Flutter/Define-defaults.xcconfig: create from the resource App-defaults.xcconfig

(fallback DARTDEFINESAPP_NAME for the plain, no-flavor Debug/Release/Profile configs). Debug.xcconfig / Release.xcconfig should #include it.

1. ios/Runner/Info.plist:

- CFBundleDisplayName = $(DARTDEFINESAPPNAME) - CFBundleIdentifier = $(PRODUCTBUNDLEIDENTIFIER) (the full per-flavor id is set in the build configs - do not append $(DARTDEFINESAPPID_SUFFIX), since an empty suffix, e.g. prd, is dropped by xcodebuild -showBuildSettings).

1. Schemes xcshareddata/xcschemes/{dev,stg,prd}.xcscheme: each must reference

Debug-<flavor> / Release-<flavor> / Profile-<flavor> and carry the standard Flutter <PreActions> "Run Prepare Flutter Framework Script" block. Keep Runner.xcscheme as a no-flavor fallback.

1. ios/Podfile: map every new configuration in the project 'Runner', { ... } hash

('Debug-dev' => :debug, 'Release-stg' => :release, ...) and set platform :ios, '13.0'.

1. ios/.gitignore: ignore only Flutter/Generated.xcconfig and

Flutter/flutterexportenvironment.sh - the <Mode>-<flavor>.xcconfig files are committed source. Keep Podfile / Podfile.lock tracked (CocoaPods is still the SPM fallback for plugins without a Package.swift).

1. GoogleService-Info.plist: run the @copysecureconfigurations skill first so

ios/Runner/Firebase/GoogleService-Info.<flavor>.plist exist. The build phase added in step 3 copies the right one into the bundle per configuration.

1. Verify: flutter clean && flutter pub get && (cd ios && pod install), then for each

flavor flutter build ios --flavor <f> --dart-define-from-file=secureFiles/<f>/environment-configs.json --no-codesign and assert CFBundleDisplayName / CFBundleIdentifier / bundled GoogleService-Info.plist in build/ios/iphoneos/Runner.app. Switch flavors without flutter clean between to confirm no stale carry-over.

3. VS Code Configuration

1. Create launch.json:

- Create .vscode/launch.json using the template from resources.

4. Verification

Run the following commands to verify the setup for each environment. These match the configurations in .vscode/launch.json.

Dev Environment:

flutter run --flavor dev --dart-define-from-file=secureFiles/dev/environment-configs.json

Staging Environment:

flutter run --flavor stg --dart-define-from-file=secureFiles/stg/environment-configs.json

Production Environment:

flutter run --flavor prd --dart-define-from-file=secureFiles/prd/environment-configs.json