eas-local-build

name	eas-local-build
description	EAS local build and version management skill. Run with `/local-build`. Uses `eas build --local` to build iOS/Android locally and automatically manages version and build numbers in app.json. Triggers when user mentions build, deploy, local build, or version bump.
license	MIT
metadata	{"author":"seungmanchoi","version":"1.1.0"}
invocation	local-build

EAS Local Build Skill

Build Expo apps locally instead of using EAS cloud builds, with automatic version and build number management.

Commands

/local-build ios              # iOS production build
/local-build android          # Android production build
/local-build both             # Build both platforms
/local-build ios --patch      # Bump patch version and build (1.0.0 → 1.0.1)
/local-build ios --minor      # Bump minor version and build (1.0.0 → 1.1.0)
/local-build ios --major      # Bump major version and build (1.0.0 → 2.0.0)
/local-build --version-only   # Bump version without building
/local-build --submit         # Build and submit to store

Execution Steps

Step 0: Auto-detect Build Numbers (First-time Local Build Migration)

If buildNumber or versionCode is missing from app.json, automatically fetch the latest build numbers from EAS remote builds.

Detection Procedure

1. Check if ios.buildNumber exists in app.json
2. If missing, query EAS for the latest build numbers:

   # Get latest iOS build number
   eas build:list --platform ios --status finished --limit 1 --json --non-interactive
   
   # Get latest Android build number
   eas build:list --platform android --status finished --limit 1 --json --non-interactive
   

3. Extract appBuildVersion from JSON response for each platform
4. If no results (new app) → start with buildNumber: "1", versionCode: 1
5. If results exist → set to fetched value + 1
6. Change eas.json appVersionSource from "remote" to "local"
7. Remove autoIncrement from eas.json if present

Example: EAS reports iOS buildNumber "7", Android versionCode 7

[Auto-detect] Fetched EAS remote build numbers:
  - iOS latest buildNumber: "7"
  - Android latest versionCode: 7

Switching to local management:
  - iOS buildNumber: "8" (previous + 1)
  - Android versionCode: 8 (previous + 1)
  - eas.json appVersionSource: "remote" → "local"

Confirm with user before updating app.json and eas.json.

Step 1: Pre-check

• Read current version from app.json or app.config.ts
• Verify eas.json exists and is properly configured
• Skip Step 0 if buildNumber/versionCode already exist

Step 2: Version Management

Show current version info and confirm with user:

Current version: 1.0.0
iOS buildNumber: 8
Android versionCode: 8

Bump version? (--patch/--minor/--major or keep)

Version Bump Rules

• --patch: Bug fix (1.0.0 → 1.0.1)
• --minor: New feature (1.0.0 → 1.1.0)
• --major: Breaking change (1.0.0 → 2.0.0)

Build Number Rules

When version changes:

• iOS buildNumber: Reset to "1"
• Android versionCode: Increment by 1 (never reset — must always increase)

When version stays the same:

• iOS buildNumber: Increment by 1
• Android versionCode: Increment by 1

Step 3: Update app.json

Update the following fields in app.json under the expo object:

{
  "expo": {
    "version": "1.0.1",
    "ios": {
      "buildNumber": "1"
    },
    "android": {
      "versionCode": 9
    }
  }
}

Note: If the project uses app.config.ts, also update the APP_VERSION default value.

Step 4: Verify eas.json

Ensure eas.json is configured for local builds:

• appVersionSource should be "local" (handled in Step 0)
• autoIncrement should be removed (handled in Step 0)

Step 5: Run Build

# iOS build
eas build --local --platform ios --profile production

# Android build
eas build --local --platform android --profile production

Build output:

• iOS: .ipa file (generated in project root)
• Android: .aab file (generated in project root)

Step 6: Store Submission (--submit flag)

# iOS: Upload ipa to App Store Connect
eas submit --platform ios --path ./build-xxxxx.ipa

# Android: Upload aab to Google Play
eas submit --platform android --path ./build-xxxxx.aab

Android versionCode Rules

versionCode must never decrease — Google Play will reject it.

• New app: versionCode = 1
• Every subsequent build: always +1
• Never reset on version change, always increment
• Example: version 1.0.0 (versionCode 5) → version 1.1.0 (versionCode 6)

iOS buildNumber Rules

• buildNumber must be unique within the same version
• Can reset to "1" when version changes (allowed by Apple)
• String type ("1", "2", "3"...)

Requirements

• macOS (required for iOS builds)
• Xcode (iOS) / Android SDK (Android)
• EAS CLI installed
• Expo project with app.json and eas.json
• Build artifacts (.ipa, .aab) should be added to .gitignore