EAS Build та профілі збірки

Вступ: від локальної розробки до продакшн-білда

На етапі розробки ваш React Native застосунок виконується у середовищі Expo Go (готовий контейнер із вбудованими нативними модулями) або через Development Build (кастомна збірка з вашими власними нативними залежностями). Проте для публікації застосунку в App Store або Google Play Store потрібен продакшн-білд — оптимізований, підписаний, скомпільований бінарний файл формату .ipa (iOS) або .apk / .aab (Android).

Історично процес створення продакшн-білдів вимагав від розробника:

1. Встановлення та налаштування Android Studio із SDK, Gradle, JDK певних версій.
2. Встановлення Xcode (лише на macOS) із Command Line Tools, provisioning profiles, signing certificates.
3. Ручного керування версіями нативних залежностей, вирішення конфліктів build.gradle, Podfile, налаштування keystore для підписування Android-білдів.
4. Локальної збірки на власному комп'ютері, що займає 10–30 хвилин і споживає значні обчислювальні ресурси.

EAS Build (Expo Application Services) — це хмарна платформа для автоматизованої збірки React Native застосунків без необхідності встановлення Android Studio чи Xcode на локальній машині. Вся компіляція відбувається на віддалених серверах Expo у контейнерах із заздалегідь налаштованими залежностями.

Що таке EAS і чому це не "тільки для Expo"

Переваги EAS Build над локальною збіркою

Мета цієї лекції: від нуля до APK

Ця лекція проведе вас через весь процес створення продакшн-білду крок за кроком:

Передумови: що потрібно мати перед початком

Перед запуском EAS Build переконайтеся, що у вас є:

Крок 1: Реєстрація облікового запису Expo

1.1. Створення акаунту через веб-інтерфейс

1. Відкрийте браузер та перейдіть на https://expo.dev/signup
2. Заповніть форму реєстрації:
   • Username: унікальне ім'я користувача (буде частиною URL вашого профілю: expo.dev/@username)
   • Email: дійсна електронна пошта (для підтвердження акаунту та оповіщень про білди)
   • Password: надійний пароль (мінімум 8 символів)
3. Натисніть "Create Account"
4. Перевірте пошту та підтвердіть email через лист від noreply@expo.dev

1.2. Автентифікація в CLI

Після створення акаунту потрібно авторизувати Expo CLI на вашому комп'ютері:

npx expo login

# Якщо ви встановили expo-cli глобально
expo login

Інтерактивний процес автентифікації:

1.3. Перевірка автентифікації

Переконайтеся, що CLI успішно авторизований:

npx expo whoami

Очікуваний вивід:

Якщо замість імені ви бачите Not logged in, повторіть команду npx expo login.

Крок 2: Ініціалізація EAS Build у проєкті

2.1. Встановлення EAS CLI

EAS CLI — це окремий інструмент командного рядка для роботи з Expo Application Services. Він не входить у базовий expo-cli.

npm install -g eas-cli

yarn global add eas-cli

pnpm add -g eas-cli

Перевірка встановлення:

eas --version

2.2. Прив'язка проєкту до Expo-акаунту

Перейдіть у кореневу директорію вашого React Native проєкту:

cd /path/to/your/project

Виконайте ініціалізацію EAS:

eas init

Інтерактивний процес:

Ця команда:

1. Створює унікальний Project ID для вашого застосунку в хмарній інфраструктурі Expo.
2. Додає поле "extra.eas.projectId" до файлу app.json або app.config.js.
3. Дозволяє вам відстежувати білди, логи, crashes через веб-дашборд expo.dev.

Зміни в app.json:

{
  "expo": {
    "name": "My App",
    "slug": "my-app",
    "version": "1.0.0",
    "extra": {
      "eas": {
        "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}

2.3. Створення конфігураційного файлу eas.json

Файл eas.json — це центральна конфігурація всіх профілів збірки. Створіть його через команду:

eas build:configure

Інтерактивний діалог:

Структура згенерованого eas.json:

Пояснення полів:

Крок 3: Налаштування профілів збірки

3.1. Профіль development (для розробки)

Цей профіль створює Development Build — версію застосунку з увімкненим Dev Menu, Hot Reload та можливістю підключення до Metro bundler.

Конфігурація:

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "android": {
        "buildType": "apk"
      },
      "ios": {
        "simulator": true
      },
      "env": {
        "API_URL": "http://localhost:3000"
      }
    }
  }
}

Пояснення параметрів:

3.2. Профіль preview (для тестування)

Цей профіль створює білд, максимально наближений до production, але призначений для внутрішнього тестування командою QA або бета-тестерами.

{
  "build": {
    "preview": {
      "distribution": "internal",
      "android": {
        "buildType": "apk"
      },
      "env": {
        "API_URL": "https://staging-api.myapp.com"
      }
    }
  }
}

Відмінності від production:

• Використовується staging API замість production.
• Може мати окремий Bundle Identifier (наприклад, com.myapp.staging) для встановлення поруч із production-версією.
• Логування та дебаг-інформація може бути більш детальною.

3.3. Профіль production (для релізу)

Фінальний профіль для публікації в App Store та Google Play Store.

{
  "build": {
    "production": {
      "android": {
        "buildType": "app-bundle"
      },
      "env": {
        "API_URL": "https://api.myapp.com"
      }
    }
  }
}

Критичні параметри production:

3.4. Версіонування білдів

Кожен білд повинен мати унікальний номер версії та build number. EAS підтримує автоматичний інкремент.

Додайте до eas.json:

{
  "build": {
    "production": {
      "autoIncrement": true,
      "android": {
        "buildType": "app-bundle"
      }
    }
  }
}

Версії в app.json:

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

Крок 4: Перший білд для Android

4.1. Запуск хмарної збірки

Тепер, коли все налаштовано, запустимо першу збірку для Android у профілі preview:

eas build --platform android --profile preview

Розбір команди:

4.2. Інтерактивний процес першого білду

При першому запуску EAS запитає кілька критичних параметрів:

Що відбувається під капотом:

1. Генерація Android Keystore:
   • Keystore — це файл з приватним ключем для підписування APK/AAB.
   • Без підписування Google Play не приймає білди.
   • EAS автоматично генерує keystore і зберігає його у захищеному хмарному сховищі.
   • Критично: Ніколи не втрачайте keystore! Без нього неможливо оновити застосунок у Google Play.
2. Завантаження коду на сервери Expo:
   • Весь вихідний код упаковується та надсилається у хмару.
   • Виключені папки (з .gitignore, .easignore) не завантажуються.
3. Запуск Docker-контейнера:
   • На серверах AWS запускається ізольований контейнер з Android SDK, Gradle, Node.js.
   • Встановлюються залежності: npm install або yarn install.
   • Виконується збірка нативного коду через Gradle.

eas credentials

4.3. Моніторинг процесу збірки

EAS Build надає детальні логи в реальному часі. Відкрийте посилання з термінала у браузері:

https://expo.dev/accounts/your_username/projects/my-app/builds/abc123

Веб-інтерфейс білду:

flowchart TD
    A["🔄 Build Queue<br/>(Waiting for available worker)"] --> B["📦 Installing dependencies<br/>npm install / yarn"]
    B --> C["🔧 Prebuild<br/>(Generate native code)"]
    C --> D["⚙️ Gradle Build<br/>(Compile Java/Kotlin)"]
    D --> E["✍️ Signing APK<br/>(Apply keystore signature)"]
    E --> F["✅ Build Complete<br/>(Artifact ready for download)"]
    
    style A fill:#FEF3C7,stroke:#1E293B,color:#1E293B
    style B fill:#DBEAFE,stroke:#1E293B,color:#1E293B
    style C fill:#DBEAFE,stroke:#1E293B,color:#1E293B
    style D fill:#DBEAFE,stroke:#1E293B,color:#1E293B
    style E fill:#DBEAFE,stroke:#1E293B,color:#1E293B
    style F fill:#DCFCE7,stroke:#1E293B,color:#1E293B

Типовий час збірки:

4.4. Завантаження готового APK

Коли збірка завершиться успішно, ви побачите:

Три способи встановлення APK:

# Завантажте APK локально
curl -o build.apk "https://expo.dev/artifacts/eas/abc123.apk"

# Підключіть Android-пристрій через USB
# Увімкніть USB Debugging у Developer Options

# Встановіть APK
adb install build.apk

4.5. Тестування встановленого білду

Після встановлення APK:

1. Перевірте іконку застосунку на домашньому екрані
2. Запустіть застосунок і переконайтеся, що всі екрани працюють
3. Перевірте мережеві запити (чи підключається до правильного API endpoint)
4. Перевірте дозволи (камера, локація, сховище) — Android покаже діалоги при першому запиті

# Відфільтруйте логи лише від вашого застосунку
adb logcat | grep "com.yourcompany.myapp"

Крок 5: Перший білд для iOS

5.1. Вимоги для iOS-збірки

На відміну від Android, збірка для iOS має додаткові обмеження:

eas build --platform ios --profile preview

5.2. Налаштування Apple Developer облікового запису

Перед першою iOS-збіркою потрібно зареєструвати ваш Bundle Identifier:

1. Відкрийте developer.apple.com/account
2. Увійдіть з Apple ID, прив'язаним до Developer Program
3. Перейдіть до Certificates, Identifiers & Profiles
4. Натисніть Identifiers → + (додати новий)
5. Оберіть App IDs → Continue
6. Заповніть форму:
   • Description: My App
   • Bundle ID: com.yourcompany.myapp (має збігатися з app.json)
   • Capabilities: оберіть потрібні дозволи (Push Notifications, Sign in with Apple тощо)
7. Натисніть Register

5.3. Запуск iOS-збірки з автоматичним підписуванням

EAS Build може автоматично згенерувати всі необхідні сертифікати:

eas build --platform ios --profile preview

Інтерактивний процес:

Що відбувається:

1. EAS відкриває браузер для автентифікації з Apple ID
2. Після входу генерується Distribution Certificate (приватний ключ для підписування)
3. Створюється Provisioning Profile (список пристроїв, на які можна встановити білд)
4. Сертифікати зберігаються у хмарі Expo
5. Білд запускається на серверах з використанням цих сертифікатів

5.4. Типи iOS білдів

iOS має три основні типи дистрибуції:

Для профілю preview рекомендовано:

{
  "build": {
    "preview": {
      "distribution": "internal",
      "ios": {
        "simulator": false
      }
    }
  }
}

EAS автоматично створить Ad Hoc білд, який можна встановити на зареєстровані пристрої.

5.5. Реєстрація пристроїв для Ad Hoc білдів

Щоб встановити Ad Hoc білд, потрібно зареєструвати UDID пристрою:

eas device:create

Інтерактивний процес:

Після реєстрації пристрою потрібно перезапустити білд:

eas build --platform ios --profile preview

EAS автоматично оновить Provisioning Profile, включивши новий UDID.

Крок 6: Локальна збірка (без хмари)

6.1. Коли потрібна локальна збірка?

EAS Build підтримує локальну компіляцію на вашому власному комп'ютері. Це корисно для:

• Корпоративних політик безпеки: Код не може залишати локальну мережу.
• Економії білдів: Free tier обмежений 30 білдами/місяць, локальні білди безкоштовні.
• Швидкого прототипування: Не потрібно чекати у черзі на хмарних серверах.
• Налагодження складних збірок: Повний доступ до логів Gradle/Xcode.

6.2. Підготовка до локальної збірки Android

Встановіть необхідні інструменти:

# Встановіть Homebrew (якщо ще немає)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Встановіть JDK 17 (вимога для React Native 0.73+)
brew install openjdk@17

# Додайте JDK до PATH
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Перевірте версію
java -version

setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"
setx PATH "%PATH%;%LOCALAPPDATA%\Android\Sdk\platform-tools"

# Ubuntu/Debian
sudo apt update
sudo apt install openjdk-17-jdk

# Встановіть Android SDK через sdkmanager
wget https://dl.google.com/android/repository/commandlinetools-linux-latest.zip
unzip commandlinetools-linux-latest.zip -d $HOME/android-sdk
export ANDROID_HOME=$HOME/android-sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin

Перевірте налаштування:

# Перевірте Java
java -version
# Очікуваний вивід: openjdk version "17.0.x"

# Перевірте Android SDK
echo $ANDROID_HOME
# Очікуваний вивід: /Users/username/Library/Android/sdk (macOS)

6.3. Запуск локального білду Android

eas build --platform android --profile preview --local

Процес збірки:

Результат:

Готовий APK буде збережений локально у папці android/app/build/outputs/apk/release/.

# Увімкніть Gradle Daemon для кешування
echo "org.gradle.daemon=true" >> android/gradle.properties

# Збільште heap memory для Gradle
echo "org.gradle.jvmargs=-Xmx4096m" >> android/gradle.properties

6.4. Локальний білд iOS (лише macOS)

Передумови:

# Встановіть Xcode з App Store (20+ GB)
# Встановіть Command Line Tools
xcode-select --install

# Встановіть CocoaPods
sudo gem install cocoapods

# Перевірте версії
xcodebuild -version
pod --version

Запуск локального білду:

eas build --platform ios --profile preview --local

Крок 7: Змінні оточення та секрети

7.1. Проблема захищених даних у коді

Реальні застосунки містять конфіденційні дані:

• API ключі сторонніх сервісів (Stripe, Firebase, Google Maps)
• Токени автентифікації
• URL-адреси внутрішніх серверів
• Секретні ключі шифрування

Зберігання таких даних безпосередньо у коді неприпустимо з міркувань безпеки:

// ❌ НЕБЕЗПЕЧНО: Ключ доступний у публічному репозиторії
const STRIPE_SECRET_KEY = "sk_live_abc123xyz";

7.2. Змінні оточення через eas.json

Базовий спосіб — визначити змінні у профілі збірки:

{
  "build": {
    "production": {
      "env": {
        "API_URL": "https://api.myapp.com",
        "ANALYTICS_KEY": "UA-123456-1",
        "FEATURE_FLAG_NEW_UI": "true"
      }
    },
    "preview": {
      "env": {
        "API_URL": "https://staging-api.myapp.com",
        "ANALYTICS_KEY": "UA-123456-2",
        "FEATURE_FLAG_NEW_UI": "false"
      }
    }
  }
}

Доступ у коді:

// app.config.js
export default {
  expo: {
    name: "My App",
    extra: {
      apiUrl: process.env.API_URL,
      analyticsKey: process.env.ANALYTICS_KEY,
    },
  },
};

// App.tsx
import Constants from "expo-constants";

const API_URL = Constants.expoConfig?.extra?.apiUrl;

console.log(API_URL);
// Production: "https://api.myapp.com"
// Preview: "https://staging-api.myapp.com"

7.3. Захищені секрети через EAS Secrets

EAS надає окреме захищене сховище для конфіденційних даних:

eas secret:create --scope project --name STRIPE_SECRET_KEY --value sk_live_abc123xyz

Параметри команди:

Перегляд збережених секретів:

eas secret:list

Використання секретів у профілях:

{
  "build": {
    "production": {
      "env": {
        "API_URL": "https://api.myapp.com",
        "STRIPE_KEY": "$STRIPE_SECRET_KEY"
      }
    }
  }
}

const stripeKey = process.env.STRIPE_KEY; // "sk_live_abc123xyz"

7.4. Файл .env для локальної розробки

Для роботи у режимі expo start використовуйте файл .env:

Встановіть бібліотеку для завантаження .env:

npm install react-native-dotenv

Налаштуйте babel.config.js:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    plugins: [
      [
        "module:react-native-dotenv",
        {
          moduleName: "@env",
          path: ".env",
        },
      ],
    ],
  };
};

Використання у коді:

import { API_URL, STRIPE_KEY } from "@env";

console.log(API_URL); // http://localhost:3000 (під час розробки)

7.5. Умовна логіка на основі середовища

Часто потрібно виконувати різний код залежно від профілю збірки:

// config.ts
import Constants from "expo-constants";

const ENV = {
  development: {
    apiUrl: "http://localhost:3000",
    enableLogging: true,
    crashReportingEnabled: false,
  },
  preview: {
    apiUrl: "https://staging-api.myapp.com",
    enableLogging: true,
    crashReportingEnabled: true,
  },
  production: {
    apiUrl: "https://api.myapp.com",
    enableLogging: false,
    crashReportingEnabled: true,
  },
};

// Визначення поточного середовища
function getEnvVars() {
  if (__DEV__) {
    return ENV.development;
  } else if (Constants.expoConfig?.extra?.profile === "preview") {
    return ENV.preview;
  }
  return ENV.production;
}

export default getEnvVars();

Налаштування app.config.js для передачі профілю:

export default {
  expo: {
    name: "My App",
    extra: {
      profile: process.env.EAS_BUILD_PROFILE || "development",
    },
  },
};

Використання у застосунку:

import config from "./config";
import * as Sentry from "@sentry/react-native";

if (config.crashReportingEnabled) {
  Sentry.init({
    dsn: "https://your-sentry-dsn",
    environment: config.apiUrl.includes("staging") ? "staging" : "production",
  });
}

console.log(`Connecting to: ${config.apiUrl}`);

Крок 8: Автоматизація через GitHub Actions

8.1. Навіщо потрібен CI/CD для мобільних білдів?

Автоматизація збірок через Continuous Integration/Continuous Deployment дає:

• Автоматичні білди при кожному commit у певну гілку (наприклад, main, develop).
• Паралельні білди iOS + Android за одну команду.
• Сповіщення команди у Slack/Discord/Telegram при успішному білді або помилці.
• Автоматичне тестування перед білдом (unit tests, E2E tests).
• Збереження артефактів для швидкого доступу до APK/IPA файлів.

8.2. Створення GitHub Action для EAS Build

Створіть файл .github/workflows/eas-build.yml у вашому репозиторії:

8.3. Налаштування EXPO_TOKEN секрету

Для автентифікації GitHub Actions у EAS потрібен токен доступу:

Крок 1: Згенеруйте токен:

eas whoami

Переконайтеся, що ви авторизовані, потім:

# Відкрийте веб-панель Expo
open https://expo.dev/accounts/[your-username]/settings/access-tokens

У веб-інтерфейсі:

1. Натисніть "Create Token"
2. Назва: GitHub Actions CI
3. Scope: Read and Write
4. Скопіюйте згенерований токен (починається з eas_...)

Крок 2: Додайте секрет у GitHub:

1. Відкрийте ваш репозиторій на GitHub
2. Перейдіть до Settings → Secrets and variables → Actions
3. Натисніть "New repository secret"
4. Name: EXPO_TOKEN
5. Value: вставте токен
6. Натисніть "Add secret"

8.4. Розширена конфігурація з тестуванням

Додайте автоматичні тести перед білдом:

name: EAS Build with Tests

on:
  push:
    branches: [main, develop]

jobs:
  test:
    name: Run Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: npm
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run TypeScript check
        run: npm run tsc --noEmit
      
      - name: Run ESLint
        run: npm run lint
      
      - name: Run unit tests
        run: npm test -- --coverage
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/coverage-final.json

  build-android:
    name: Build Android
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20.x
          cache: npm
      
      - name: Setup Expo
        uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      
      - run: npm ci
      
      - name: Build Android APK
        run: |
          eas build --platform android \
            --profile preview \
            --non-interactive \
            --no-wait

  build-ios:
    name: Build iOS
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20.x
      
      - name: Setup Expo
        uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      
      - run: npm ci
      
      - name: Build iOS IPA
        run: |
          eas build --platform ios \
            --profile production \
            --non-interactive \
            --no-wait

Логіка workflow:

1. test job: Виконується завжди при push або PR
   • TypeScript перевірка
   • ESLint для якості коду
   • Unit тести з покриттям
2. build-android job: Виконується лише після успішних тестів
   • Запускається для main та develop гілок
3. build-ios job: Виконується лише для main гілки
   • Production білд для App Store

- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: |
      node_modules
      ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

8.5. Сповіщення у Slack при завершенні білду

Додайте нотифікацію команди:

- name: Notify Slack on success
  if: success()
  uses: slackapi/slack-github-action@v1
  with:
    webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
    payload: |
      {
        "text": "✅ EAS Build successful for ${{ github.ref }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*Build completed*\n• Platform: Android\n• Profile: preview\n• Branch: `${{ github.ref_name }}`\n• Commit: ${{ github.event.head_commit.message }}"
            }
          },
          {
            "type": "actions",
            "elements": [
              {
                "type": "button",
                "text": {
                  "type": "plain_text",
                  "text": "View Build"
                },
                "url": "https://expo.dev/accounts/your-username/projects/my-app/builds"
              }
            ]
          }
        ]
      }

- name: Notify Slack on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
    payload: |
      {
        "text": "❌ EAS Build failed for ${{ github.ref }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*Build failed*\n• Platform: Android\n• Branch: `${{ github.ref_name }}`\n• <${{ github.event.head_commit.url }}|View commit>"
            }
          }
        ]
      }

Налаштування Slack Webhook:

1. Відкрийте api.slack.com/apps
2. Create New App → From scratch
3. Incoming Webhooks → Activate
4. Add New Webhook to Workspace → оберіть канал (наприклад, #builds)
5. Скопіюйте Webhook URL
6. Додайте секрет SLACK_WEBHOOK_URL у GitHub Repository Settings

Підсумки: Чек-лист продакшн-білду

Типові помилки та їх вирішення

# macOS
brew install openjdk@17
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v17)' >> ~/.zshrc
source ~/.zshrc

# Перевірка
echo $JAVA_HOME
java -version

# Видаліть старий keystore
eas credentials

# Оберіть: Android → Production → Keystore → Remove
# Згенеруйте новий при наступному білді
eas build --platform android --profile production

::

# Перегенеруйте сертифікати
eas credentials

# Оберіть: iOS → Production → Distribution Certificate → Create new
# Слідуйте інструкціям для автентифікації з Apple ID

::

Наступні кроки: публікація у стори

Після успішної збірки та тестування білду ви готові до публікації:

eas build --platform all --profile production

eas submit --platform android --profile production
eas submit --platform ios --profile production

Додаткові ресурси