# Expo SDK Upgrade Workflows and EAS Configuration for Plugins: A Complete Guide

> Master Expo SDK upgrade workflows and EAS configuration for plugins. Automate SDK bumps native builds and web deployments with our comprehensive guide.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Expo SDK upgrade workflows and EAS configuration for plugins provide deterministic CLI commands, breaking-change checklists, and ready-to-use GitHub Actions YAML to automate SDK bumps, web deployments, and native builds.**

The openai/plugins repository contains opinionated skills for managing Expo projects, including step-by-step upgrade procedures and Expo Application Services (EAS) CI/CD configurations. This guide extracts the practical implementation details from `plugins/expo/skills/upgrading-expo` and `plugins/expo/skills/expo-deployment`, showing you how to safely migrate between SDK versions and automate your release pipeline.

## Upgrade Process for Expo SDK Versions

The core upgrade sequence lives in [`plugins/expo/skills/upgrading-expo/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/upgrading-expo/SKILL.md) and follows a strict order to prevent dependency drift and native build failures.

### CLI Workflow for SDK Bumps

Start every upgrade with the official Expo CLI to ensure peer dependencies align with the new SDK:

```bash

# 1️⃣ Upgrade SDK and fix mismatched dependencies

npx expo install expo@latest
npx expo install --fix

# 2️⃣ Diagnose known issues before proceeding

npx expo-doctor

```

The `--fix` flag automatically resolves version mismatches in [`package.json`](https://github.com/openai/plugins/blob/main/package.json), while `expo-doctor` scans for deprecated APIs and incompatible native modules.

### Cache Clearing and Native Pre-build

Dirty caches cause cryptic Metro or Xcode errors after upgrades. The skill mandates a full cache purge before rebuilding:

```bash

# Clear Metro, TypeScript, and watchman caches

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

```

For **bare workflow** projects (those with `ios/` or `android/` directories), regenerate native projects to apply SDK changes:

```bash
npx expo prebuild --clean

```

Additional platform-specific cleanup includes `pod deintegrate` for iOS CocoaPods and `./gradlew clean` for Android, as documented in the cache-clearing section of [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md).

## Breaking-Change Checklists and Migration Paths

The `upgrading-expo` skill maintains concise checklists covering API removals, import path changes, and React 19 compatibility.

### React 19 API Changes

According to [`plugins/expo/skills/upgrading-expo/references/react-19.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/upgrading-expo/references/react-19.md), modern Expo SDKs (50+) require specific pattern updates:

- Replace `useContext` with `use`
- Remove `.Provider` suffix from context providers
- Eliminate `forwardRef` in favor of standard ref passing

These changes affect how plugins consume React context and must be applied before the SDK 53+ new architecture becomes mandatory.

### Native Module and Hermes Updates

| Migration Area | Verification Step |
|---------------|-------------------|
| **Removed APIs** | Review https://expo.dev/changelog for deprecated methods |
| **Import Path Moves** | Update `expo-something` imports to new module locations |
| **Native Pre-build Requirements** | Some modules (e.g., `expo-audio`, `expo-video`) now require `npx expo prebuild` |
| **Hermes v1** | Add `useHermesV1: true` in `expo-build-properties` for legacy engine support |

The new architecture reference file at [`plugins/expo/skills/upgrading-expo/references/new-architecture.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/upgrading-expo/references/new-architecture.md) details Fabric renderer and TurboModule requirements enabled by default in SDK 53+.

## EAS Configuration for CI/CD Workflows

EAS workflows reside in [`plugins/expo/skills/expo-deployment/references/workflows.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/expo-deployment/references/workflows.md). These YAML files belong in `.eas/workflows/` (or mirrored to `.github/workflows/`) and enable fully automated build, preview, and submission pipelines.

### Web Deployment Automation

Trigger production web deployments on every push to `main`:

```yaml

# .eas/workflows/deploy.yml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy_web:
    type: deploy
    params:
      prod: true

```

### PR Preview Workflows

Generate instant web previews for pull requests without consuming native build credits:

```yaml

# .eas/workflows/web-pr-preview.yml

name: Web PR Preview
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  preview:
    type: deploy
    params:
      prod: false

```

For native over-the-air (OTA) updates during PR review, use the `update` job type instead:

```yaml

# .eas/workflows/pr-preview.yml

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  publish:
    type: update
    params:
      branch: "pr-${{ github.event.pull_request.number }}"
      message: "PR #${{ github.event.pull_request.number }}"

```

### Production Release Pipelines

Automate store submissions by chaining build and submit jobs when version tags are pushed:

```yaml

# .eas/workflows/release.yml

name: Release
on:
  push:
    tags: ['v*']
jobs:
  build-ios:
    type: build
    params:
      platform: ios
      profile: production
  build-android:
    type: build
    params:
      platform: android
      profile: production
  submit-ios:
    type: submit
    needs: [build-ios]
    params:
      platform: ios
      profile: production
  submit-android:
    type: submit
    needs: [build-android]
    params:
      platform: android
      profile: production

```

### Conditional Build Optimization

Skip unnecessary builds when changes only affect documentation by checking file paths:

```yaml

# .eas/workflows/conditional-release.yml

name: Conditional Release
on:
  push:
    branches: [main]
jobs:
  check-changes:
    type: run
    params:
      command: |
        if git diff --name-only HEAD~1 | grep -q "^src/"; then
          echo "has_changes=true" >> $GITHUB_OUTPUT
        fi
  build:
    type: build
    needs: [check-changes]
    if: needs.check-changes.outputs.has_changes == 'true'
    params:
      platform: all
      profile: production

```

**Security best practices** from the workflow reference mandate storing API keys and certificates in **EAS Secrets** rather than workflow files, and using `workflow_dispatch` triggers for manual emergency releases.

## Summary

- **Upgrade CLI**: Use `npx expo install expo@latest --fix` followed by `expo-doctor` and aggressive cache clearing via `expo export --clear` and `watchman watch-del-all`.
- **Native Regeneration**: Run `npx expo prebuild --clean` for bare workflow projects to apply SDK-level native changes.
- **Breaking Changes**: Address React 19 patterns (`use` instead of `useContext`), verify import paths, and opt into Hermes v1 via `expo-build-properties` when necessary.
- **EAS Automation**: Deploy web builds on `main` pushes, create PR previews with the `update` job type, and chain `build` → `submit` jobs for automated store releases.
- **Source Locations**: Reference [`plugins/expo/skills/upgrading-expo/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/upgrading-expo/SKILL.md) for upgrade logic and [`plugins/expo/skills/expo-deployment/references/workflows.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/expo-deployment/references/workflows.md) for CI/CD templates.

## Frequently Asked Questions

### How do I handle native build failures after upgrading Expo SDK?

Native build failures typically indicate stale caches or mismatched native code. According to [`plugins/expo/skills/upgrading-expo/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/upgrading-expo/SKILL.md), run `npx expo prebuild --clean` to regenerate `ios/` and `android/` directories, then clear platform-specific caches (CocoaPods `pod deintegrate` and Gradle `./gradlew clean`). This ensures the new SDK's native modules compile against fresh project files.

### What is the difference between EAS `deploy` and `update` job types?

The `deploy` job type in EAS workflows publishes web builds to Expo Hosting or external providers, while the `update` job pushes over-the-air (OTA) JavaScript bundles to native apps already installed on devices. Use `deploy` for web previews and `update` for testing native changes without submitting to app stores.

### When should I use Hermes v1 instead of the default Hermes version?

Hermes v1 is required only when maintaining compatibility with legacy tooling or specific profiling requirements. As noted in the upgrade skill, add `useHermesV1: true` to your `expo-build-properties` plugin configuration if your monitoring tools or crash reporters require the older Hermes bytecode format. Modern projects should default to the SDK-recommended Hermes version.

### How do I prevent EAS from building on documentation-only changes?

Implement a conditional workflow using the `run` job type to check git diff paths before triggering expensive native builds. The workflow references in [`plugins/expo/skills/expo-deployment/references/workflows.md`](https://github.com/openai/plugins/blob/main/plugins/expo/skills/expo-deployment/references/workflows.md) demonstrate parsing `git diff --name-only HEAD~1` for `src/` directory changes and setting output variables that subsequent `build` jobs reference in their `if` conditions.