How Expo Plugin Workflows Handle EAS Builds and SDK Upgrades

Expo plugin workflows automate EAS builds and SDK upgrades by executing the upgrading-expo skill—a deterministic sequence of CLI commands including npx expo install expo@latest and expo prebuild --clean—before every build to synchronize native code and dependencies with the target SDK version.

The openai/plugins repository defines reusable Expo tooling that runs during development, CI, and EAS (Expo Application Services) builds. These Expo plugin workflows handle EAS builds and SDK upgrades through a declarative skill system that ensures reproducible native project generation and dependency alignment.

Architecture of Expo Plugin Workflows

The workflow architecture centers on the plugins/expo/ directory, which houses skill modules that the CLI invokes during build processes. According to the source code in the openai/plugins repository, the system operates through four primary components:

• plugins/expo/skills/ – Contains domain-specific skills like upgrading-expo that expose commands for SDK management.
• eas.json – Declares build profiles, distribution channels, and environment variables that EAS reads before container initialization.
• expo prebuild – Generates or updates native ios/ and android/ directories based on app.json configurations and plugin modifications.
• expo-doctor – Validates project health against target SDK requirements, surfacing breaking changes before compilation.

When a build triggers, EAS reads the eas.json configuration, launches a container, and automatically executes any plugin steps defined in the plugins/expo/ directory. This process ensures that native code changes and SDK migrations occur before compilation begins.

EAS Build Integration

EAS builds integrate with Expo plugins through the Continuous Native Generation (CNG) and bare workflow paths. The build process follows a strict execution order defined in the repository's skill files.

First, EAS evaluates the eas.json profile to determine the target environment. For builds requiring native modifications, the CLI automatically invokes expo prebuild to regenerate platform-specific directories. Plugins can modify app.json during this phase to inject build-time settings such as Hermes v1 configurations or New Architecture flags.

The critical integration point occurs in plugins/expo/skills/upgrading-expo/SKILL.md, which provides the Step-by-Step Upgrade Process executed before the build compiles. This ensures the project matches the intended SDK version specified in environment variables or configuration files.

SDK Upgrade Automation

The upgrading-expo skill automates SDK migrations through a canonical checklist documented in plugins/expo/skills/upgrading-expo/SKILL.md. This deterministic process eliminates manual intervention during version bumps.

Step-by-Step Upgrade Process

The skill executes the following commands in sequence:

1. Upgrade Core Dependencies

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

2. Validate Project Health

   npx expo-doctor

3. Clear Caches

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

4. Regenerate Native Code

   npx expo prebuild --clean

Advanced Configuration Options

The skill handles edge cases specific to recent SDK versions:

• Beta/Preview Releases – Install with npx expo install expo@next --fix for early SDK access.
• Hermes v1 – Set useHermesV1: true in expo-build-properties for SDK 55+ (lines 27-30 of SKILL.md).
• New Architecture – Enabled by default from SDK 53+; no manual newArchEnabled flag required (lines 31-34 of SKILL.md).

Implementation Examples

Configuring eas.json for SDK Enforcement

Create a production profile that passes SDK version constraints to plugin workflows:

{
  "build": {
    "production": {
      "developmentClient": false,
      "releaseChannel": "production",
      "distribution": "store",
      "android": {
        "buildType": "apk"
      },
      "ios": {
        "simulator": false
      },
      "env": {
        "EXPO_SDK_VERSION": "latest"
      }
    }
  }
}

CI Pipeline Script

Automate the complete upgrade and build workflow in CI:

#!/usr/bin/env bash
set -euo pipefail

# Ensure target SDK alignment

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

# Surface breaking changes

npx expo-doctor || true

# Clean caches for bare workflow

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

# Conditional native regeneration

if [ -d ios ] || [ -d android ]; then
  npx expo prebuild --clean
fi

# Execute EAS build

eas build --profile production --platform all

Enabling React Compiler (SDK 54+)

Configure experimental features in app.json:

{
  "expo": {
    "sdkVersion": "54.0.0",
    "experiments": {
      "reactCompiler": true
    }
  }
}

Key Source Files in openai/plugins

The following files define the workflow implementation:

• plugins/expo/skills/upgrading-expo/SKILL.md – Master checklist for SDK upgrades, cache clearing, and native prebuild logic.
• plugins/expo/skills/upgrading-expo/references/react-19.md – React 19 migration steps required for SDK 54+.
• plugins/expo/skills/upgrading-expo/references/expo-av-to-audio.md – Migration guide from expo-av to expo-audio.
• plugins/expo/skills/upgrading-expo/references/expo-av-to-video.md – Migration guide from expo-av to expo-video.

Summary

• Expo plugin workflows automate EAS builds through the upgrading-expo skill, which runs deterministic upgrade commands before compilation.
• The eas.json configuration drives build profiles and environment variables, while expo prebuild --clean handles native code regeneration for bare workflow projects.
• plugins/expo/skills/upgrading-expo/SKILL.md contains the canonical SDK upgrade checklist, including beta SDK handling, cache clearing, and deprecation migrations.
• Continuous Native Generation (CNG) projects skip native regeneration steps when ios/ and android/ directories do not exist, streamlining the build process.

Frequently Asked Questions

What triggers the Expo plugin workflow during an EAS build?

The EAS CLI automatically triggers plugin workflows when it detects configuration in plugins/expo/ during the pre-build phase. The container reads eas.json, executes expo prebuild if native changes are required, then runs the upgrading-expo skill to validate SDK alignment before compilation begins.

When should I run expo prebuild --clean during an SDK upgrade?

Run npx expo prebuild --clean when the upgrading-expo skill detects native module changes or when ios/ and android/ directories exist in your project. This command regenerates native project files from app.json configuration. CNG projects without existing native directories can skip this step.

How does the upgrading-expo skill handle deprecated packages like expo-av?

The skill references migration guides in plugins/expo/skills/upgrading-expo/references/—specifically expo-av-to-audio.md and expo-av-to-video.md—to automate the transition from deprecated modules to their replacements. The checklist runs npx expo install --fix to remove deprecated packages and install their modern equivalents.

What is the difference between EAS builds for bare workflow vs CNG projects?

Bare workflow projects maintain persistent ios/ and android/ directories, requiring expo prebuild --clean during SDK upgrades to regenerate native code. CNG (Continuous Native Generation) projects generate these directories ephemerally during the EAS build process and skip regeneration when directories do not exist locally, resulting in faster upgrade cycles.

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