building-with-eas

What this skill does

# EAS Build & Submit Reference

## Plugin Tools

Before production builds, verify your version hasn't already been released:

```bash
# Check version against EAS build history and store releases
cd /path/to/expo-toolkit && npm run check-version -- /path/to/your/app

# Or directly
node tools/check-version.js /path/to/your/app
node tools/check-version.js /path/to/your/app --json
```

This checks:
- Current version in app.config.js
- Recent EAS builds and their submission status
- autoIncrement settings in eas.json
- Provides guidance if version bump is needed

## Essential Commands

```bash
# Initialize EAS in project
eas init

# Configure build profiles
eas build:configure

# Check/manage credentials
eas credentials
eas credentials --platform ios
eas credentials --platform android

# Build commands
eas build --platform ios --profile development
eas build --platform android --profile preview
eas build --platform all --profile production

# Build with auto-submit
eas build --platform ios --profile production --auto-submit
eas build --platform android --profile production --auto-submit

# Check build status
eas build:list
```

## eas.json Configuration

### Standard Build Profiles

The `eas.json` file defines build profiles. A well-configured file looks like:

```json
{
  "cli": {
    "version": ">= 16.18.0",
    "appVersionSource": "remote"
  },
  "build": {
    "base": {
      "env": {
        "APP_VARIANT": "production"
      }
    },
    "development": {
      "extends": "base",
      "developmentClient": true,
      "distribution": "internal",
      "env": {
        "APP_VARIANT": "development"
      },
      "ios": {
        "simulator": false
      },
      "android": {
        "buildType": "apk",
        "gradleCommand": ":app:assembleDebug"
      }
    },
    "development-simulator": {
      "extends": "development",
      "ios": {
        "simulator": true
      },
      "android": {
        "buildType": "apk"
      }
    },
    "preview": {
      "extends": "base",
      "distribution": "internal",
      "env": {
        "APP_VARIANT": "preview"
      },
      "android": {
        "buildType": "apk"
      }
    },
    "production": {
      "extends": "base",
      "autoIncrement": true,
      "env": {
        "APP_VARIANT": "production"
      }
    }
  },
  "submit": {
    "production": {
      "ios": {
        "appleId": "[email protected]",
        "ascAppId": "1234567890"
      },
      "android": {
        "serviceAccountKeyPath": "./play-store-credentials.json",
        "track": "internal"
      }
    }
  }
}
```

### Profile Properties Reference

| Property | Description | Common Values |
|----------|-------------|---------------|
| `developmentClient` | Include expo-dev-client | `true` for dev builds |
| `distribution` | How build is distributed | `internal`, `store`, `simulator` |
| `autoIncrement` | Auto-increment version | `true`, `"version"`, `"buildNumber"` |
| `env` | Environment variables | Object of key-value pairs |
| `extends` | Inherit from another profile | Profile name string |

### iOS-Specific Properties

| Property | Description |
|----------|-------------|
| `simulator` | Build for simulator (no signing) |
| `enterpriseProvisioning` | Use enterprise distribution |
| `resourceClass` | Build machine size (`default`, `large`) |

### Android-Specific Properties

| Property | Description |
|----------|-------------|
| `buildType` | Output format (`apk` or `app-bundle`) |
| `gradleCommand` | Custom Gradle command |
| `withoutCredentials` | Skip signing (simulator/dev) |

## Credentials Management

### iOS Credentials

EAS manages three primary iOS credentials:

1. **Distribution Certificate** - Signs your app for distribution
2. **Provisioning Profile** - Links app, certificate, and devices
3. **Push Notification Key** - For APNs (Apple Push Notification service)

```bash
# Interactive credential management
eas credentials --platform ios

# Options available:
# - Distribution Certificate: Manage your distribution certificate
# - Provisioning Profile: Manage your provisioning profile
# - Push Notifications: Manage your Apple Push Notifications Key
```

**Let EAS manage credentials (recommended):**
- EAS automatically creates and manages credentials
- Certificates stored securely on Expo servers
- Automatic renewal before expiration

**Use local credentials:**
Create `credentials.json` at project root:
```json
{
  "ios": {
    "provisioningProfilePath": "ios/certs/profile.mobileprovision",
    "distributionCertificate": {
      "path": "ios/certs/dist-cert.p12",
      "password": "certificate-password"
    }
  }
}
```

### Android Credentials

Android requires a keystore for signing:

```bash
# Interactive credential management
eas credentials --platform android

# Options available:
# - Keystore: Manage your keystore
# - FCM API Key: Manage your Firebase Cloud Messaging key
```

**Local keystore configuration:**
```json
{
  "android": {
    "keystore": {
      "keystorePath": "android/keystores/release.keystore",
      "keystorePassword": "keystore-password",
      "keyAlias": "key-alias",
      "keyPassword": "key-password"
    }
  }
}
```

### Push Notification Setup

**iOS (APNs):**
```bash
eas credentials --platform ios
# Select: Push Notifications: Manage your Apple Push Notifications Key
# Follow prompts to create or upload key
```

**Android (FCM):**
```bash
eas credentials --platform android
# Select: FCM API Key: Manage your Firebase Cloud Messaging key
# Provide your FCM server key from Firebase Console
```

## Build Submission (`--auto-submit`)

### iOS Submission Behaviour

iOS builds can auto-submit to App Store Connect / TestFlight:

```bash
# Auto-submit to TestFlight
eas build --platform ios --profile production --auto-submit
```

**What happens:**
1. Build completes on EAS servers
2. Build automatically uploaded to App Store Connect
3. Appears in TestFlight for testing
4. Still requires manual submission to App Review

**Requirements:**
- Valid Apple Developer account
- `appleId` and `ascAppId` in submit profile
- App created in App Store Connect

### Android Submission Behaviour

**IMPORTANT: First submission must be manual**

For a brand new app on Google Play:
1. Build the AAB: `eas build --platform android --profile production`
2. Download the AAB from EAS dashboard
3. Manually upload to Google Play Console
4. Complete store listing, content rating, etc.
5. After first release, `--auto-submit` works

```bash
# After first manual upload, auto-submit works
eas build --platform android --profile production --auto-submit
```

**Submit profile for Android:**
```json
{
  "submit": {
    "production": {
      "android": {
        "serviceAccountKeyPath": "./play-store-credentials.json",
        "track": "internal"
      }
    }
  }
}
```

**Track options:**
- `internal` - Internal testing (up to 100 testers, instant)
- `alpha` - Closed testing
- `beta` - Open testing
- `production` - Production release

### Service Account Setup (Android)

1. Go to Google Cloud Console
2. Create service account with "Service Account User" role
3. Go to Play Console → Setup → API access
4. Link the service account
5. Grant "Release manager" permissions
6. Download JSON key file
7. Reference in `eas.json`

## Development Build Setup

### For Physical Devices

```bash
# iOS device (requires Apple Developer account)
eas build --platform ios --profile development

# Android device
eas build --platform android --profile development
```

**iOS device registration:**
- Devices must be registered in Apple Developer Portal
- EAS can register devices automatically during build
- Or register manually: `eas device:create`

### For Simulators/Emulators

```bash
# iOS Simulator
eas build --platform ios --profile development-simulator

# Android Emulator (APK works on emulators)
eas build --platform android --profile development
```

## Environment Variables

### Build-time Variables

Set in `eas.json` per profile:
```json
{
  "build": {
    "pr