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

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 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:

# 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, 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:

# 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:

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.

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, 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 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. 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:

# .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:

# .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:

# .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:

# .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:

# .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 for upgrade logic and 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}