# How Expo Plugin Workflows Handle EAS Builds and SDK Upgrades

> Learn how Expo plugin workflows streamline EAS builds and SDK upgrades using the upgrading-expo skill to automatically sync native code and dependencies before each build.

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

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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**
   ```bash
   npx expo install expo@latest
   npx expo install --fix
   ```

2. **Validate Project Health**
   ```bash
   npx expo-doctor
   ```

3. **Clear Caches**
   ```bash
   npx expo export -p ios --clear
   rm -rf node_modules .expo
   watchman watch-del-all
   ```

4. **Regenerate Native Code**
   ```bash
   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:

```json
{
  "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:

```bash
#!/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`](https://github.com/openai/plugins/blob/main/app.json):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/expo-av-to-audio.md) and [`expo-av-to-video.md`](https://github.com/openai/plugins/blob/main/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.