🛠️ Prepare the app

The Bundle ID is your app's permanent unique identifier, in reverse-DNS form: com.yourname.fittrack.

• Use a domain you control (or com.<yourname>.<app> if you have no domain). Stick to letters, digits, dots, and hyphens; case-sensitive — pick lowercase and never vary it.
• Where to set it:
  • Xcode: target → General → Identity → Bundle Identifier.
  • Expo: expo.ios.bundleIdentifier in app.json.
  • Flutter: the PRODUCT_BUNDLE_IDENTIFIER in ios/Runner.xcodeproj (edit via Xcode's General tab).
  • RN bare: Xcode, same as native.
• Registering: with automatic signing, Xcode registers the App ID for you; EAS does it during your first build. You can also register manually at developer.apple.com → Identifiers.

Two different numbers, two different jobs:

• Version (CFBundleShortVersionString, e.g. 1.0.0) — user-visible, shown on the App Store. Must increase for each released version.
• Build number (CFBundleVersion, e.g. 1, 2, 42) — must be unique and increasing for every single upload, even failed ones.

Where to set them:

• Xcode / RN bare: target → General → Identity → Version / Build.
• Expo: expo.version and expo.ios.buildNumber in app.json — or set "autoIncrement": true in eas.json production profile and never think about it again.
• Flutter: version: 1.0.0+1 in pubspec.yaml (the part after + is the build number).

Start at 1.0.0 / build 1 and increment the build number on every upload, no exceptions.

From your 1024×1024 master (Phase 1):

• Native / RN bare: in Assets.xcassets → AppIcon, set the asset to Single Size and drop in the 1024 image — modern Xcode derives every size automatically.
• Expo: point expo.icon (and optionally expo.ios.icon) at the 1024 PNG in app.json; the build pipeline generates the set.
• Flutter: use the flutter_launcher_icons package:

Verify the result by building once and checking the home-screen icon on a simulator — a missing icon slot can fail upload validation (ITMS-90022).

The deployment target is the oldest iOS version your app installs on. Don't just accept the template default:

• Supporting the last two major iOS versions covers the overwhelming majority of active devices (Apple's adoption stats: iOS N + N−1 is typically >90%).
• Each older version you support is a test burden and an API ceiling (no newer SwiftUI/StoreKit features without if #available guards).
• Where to set:
  • Xcode / RN bare: target → General → Minimum Deployments.
  • Expo: expo-build-properties plugin → ios.deploymentTarget in app.json (defaults are sensible per SDK).
  • Flutter: platform :ios, '13.0' in ios/Podfile and the Xcode target setting — keep them in sync.
• Check your dependencies: some pods/packages force a floor (e.g. a package requiring iOS 15 raises your minimum whether you like it or not).

Every protected API your app — or any SDK you embed — touches needs a NS...UsageDescription key in Info.plist, e.g.:

• NSCameraUsageDescription — camera
• NSPhotoLibraryUsageDescription — photo library
• NSLocationWhenInUseUsageDescription — location
• NSMicrophoneUsageDescription — microphone
• NSContactsUsageDescription — contacts

Write specific, user-benefit strings:

• ✅ "We use the camera to scan receipts so you don't have to type them."
• ❌ "Camera needed." (vague strings are a 5.1.1 rejection)

Where:

• Xcode / RN bare: target → Info tab.
• Expo: expo.ios.infoPlist in app.json (or via each module's config plugin options).
• Flutter: ios/Runner/Info.plist.

Audit your SDKs — image pickers, analytics, and ad SDKs often link camera/location frameworks you never call directly, and Apple's static scan doesn't care whose code it is.

Let Xcode handle certificates and provisioning profiles — manual signing is rarely worth it for a solo app.

1. Xcode → Settings → Accounts → + → sign in with your developer Apple ID. Your team should appear.
2. Open the project, select the app target → Signing & Capabilities tab.
3. Check Automatically manage signing and select your Team (the one with your Team ID, not 'Personal Team').
4. Xcode registers the App ID, creates an Apple Development certificate, and generates profiles. The Apple Distribution certificate is created on first archive/distribute if missing.
5. Resolve any red errors here now — signing errors at archive time are this same screen's problems, deferred.

Flutter users: do this inside ios/Runner.xcworkspace, on the Runner target.

Get the native side of your RN app release-ready:

1. Install pods after any native-dependency change:
2. Hermes is the default JS engine on modern RN — leave it enabled unless you have a specific reason (smaller, faster startup). Check ios/Podfile.properties.json or your Podfile for hermes_enabled.
3. Build the Release configuration locally before archiving — Debug-only bugs (dev-menu code, Metro dependency) surface here, not in review:
   • Xcode: Product → Scheme → Edit Scheme… → Run → Build Configuration → Release, then build to a device.
4. Confirm the JS bundle embeds correctly (Release builds run without Metro; if the app white-screens, the bundle step failed).

Flutter's iOS shell lives in ios/ and is configured through Xcode:

1. Open the workspace (not the project):
2. Select the Runner target → Signing & Capabilities → enable Automatically manage signing, choose your Team, and confirm the Bundle Identifier matches what you chose earlier.
3. In General, check Display Name, Version, and Build (these mirror pubspec.yaml's version: x.y.z+n).
4. Review ios/Runner/Info.plist for purpose strings and ios/Podfile for the platform floor.
5. Sanity-build a release to a device: flutter run --release.

EAS (Expo Application Services) builds, signs, and submits your app in the cloud — no Mac required.

1. Install the CLI globally and log in with your Expo account (create one at expo.dev if needed):
2. EAS Build has a free tier with queue limits; paid plans speed up the queue. Check current limits at expo.dev/pricing.
3. You'll also need your Apple Developer account credentials handy — EAS talks to Apple's APIs on your behalf to manage certificates and (later) create the App Store Connect app record.

Generate the EAS config:

1. Run the configure command — it creates eas.json with development, preview, and production build profiles.
2. Confirm expo.ios.bundleIdentifier is set in app.json (EAS will prompt if missing).
3. Recommended eas.json production tweaks:
   • "autoIncrement": true — EAS bumps the build number for you on every build, killing the 'Redundant Binary Upload' class of errors.
4. Commit eas.json to version control.

1. Kick off a production build:
2. First run, EAS asks to log into your Apple Developer account and offers to manage credentials — say yes and let EAS handle it. It will:
   • register the Bundle ID,
   • create/reuse a distribution certificate,
   • create the provisioning profile,
   • store everything encrypted on EAS servers (inspect anytime with eas credentials).
3. The build runs in the cloud (typically 10–25 min depending on queue). You get a URL to watch logs and download the .ipa.
4. Errors in native modules surface here for the first time — read the Xcode log section of failed builds; the JS logs are rarely the culprit.