How to Handle Expo and React Native SDK Upgrades in Plugins

Upgrade the SDK package using npx expo install or npm, run diagnostics with expo-doctor, clear all caches including Watchman and Gradle/CocoaPods, regenerate native projects with prebuild --clean for bare workflows, and validate against breaking changes before enabling new features like React Compiler.

Managing SDK upgrades in plugin development requires careful coordination between JavaScript dependencies and native code. The openai/plugins repository provides structured workflows for handling Expo and React Native SDK upgrades in plugins, ensuring compatibility across JavaScript and native layers. These upgrade paths cover everything from Metro configuration changes to CocoaPods regeneration, specifically targeting plugins that integrate third-party SDKs like Zoom Meeting SDK.

Expo SDK Upgrade Workflow

The upgrade process for Expo-based plugins follows a three-phase approach documented in [plugins/expo/skills/upgrading-expo/SKILL.md](https://github.com/openai/plugins/blob/main/plugins/expo/skills/upgrading-expo/SKILL.md). This workflow handles both managed and bare workflows while accounting for breaking changes in native modules.

Initial Upgrade and Diagnostics

Start by pulling the latest stable SDK and aligning peer dependencies. The diagnostic tool detects version mismatches before you proceed to native cleanup.

# Upgrade to latest Expo SDK

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

# Validate dependency alignment

npx expo-doctor

Running expo-doctor is critical because it identifies mismatched versions and missing native modules that could cause runtime crashes after the upgrade.

Native Cleanup and Pre-build Regeneration

For bare workflow plugins, you must regenerate native directories to reflect SDK changes. Clear CocoaPods and Gradle caches to prevent stale artifacts from causing build failures.

# Clear JavaScript and Expo caches

watchman watch-del-all
rm -rf node_modules .expo
npm install

# Regenerate native projects (bare workflow only)

npx expo prebuild --clean

# iOS cleanup

cd ios && pod install --repo-update

# Android cleanup

cd android && ./gradlew clean

The npx expo prebuild --clean command regenerates ios/ and android/ directories when native changes are required, ensuring the underlying native code matches the upgraded JavaScript API surface.

Configuration Migration and Housekeeping

Modern Expo SDKs require specific configuration updates. Remove legacy files that conflict with new defaults and update your app.json to exclude resolved workarounds.

Key migrations include:

• Delete babel.config.js and metro.config.js if they contain legacy resolver flags like experimentalImportSupport or EXPO_USE_FAST_RESOLVER
• Remove autoprefixer when upgrading to SDK 53+
• Update expo.install.exclude to remove entries like "react-native-reanimated" after the upgrade completes

React Native SDK Upgrade Workflow (Zoom Example)

Third-party React Native SDKs like Zoom Meeting SDK follow similar patterns with additional native-specific steps. The workflow in [plugins/zoom/skills/meeting-sdk/react-native/SKILL.md](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/meeting-sdk/react-native/SKILL.md) details the upgrade path for maintaining the native bridge.

Package Updates and Native Rebuild

Upgrade the wrapper package to match the underlying native SDK version, then force a rebuild of native modules.

# Upgrade Zoom SDK (example)

npm i @zoom/meetingsdk-react-native@latest

# Rebuild native dependencies

npx pod-install        # iOS

./gradlew clean        # Android

After installation, run diagnostics to verify peer dependency alignment. For Expo projects, use npx expo-doctor; for pure React Native projects, use npx react-native doctor.

Breaking Change Validation

Check the SDK release notes for removed APIs, renamed enums, and required permission changes. Test core functionality including camera access, audio recording, and video sharing to confirm the bridge between JavaScript and native code remains intact.

Critical Configuration Changes for Modern SDKs

Expo SDK 54+ and React Native 0.75+ introduce significant architectural changes that plugins must adopt to maintain compatibility.

Replacing Deprecated Packages

Several core packages have been removed or split in recent SDK versions. Update your imports to prevent runtime errors:

• Replace expo-av with expo-audio and expo-video
• Replace @expo/vector-icons with expo-symbols
• Replace AsyncStorage with expo-sqlite, localStorage, or expo-secure-store

Enabling React Compiler and Hermes v1

For SDK 54 and above, enable the React Compiler and install required worklet packages to align with new defaults:

npx expo install react-native-worklets

Add the following to your app.json:

{
  "experiments": {
    "reactCompiler": true
  }
}

For SDK 55+, optionally enable Hermes v1 by adding useHermesV1: true in expo-build-properties to improve runtime performance.

Summary

• Upgrade the SDK package using npx expo install expo@latest or npm i @vendor/sdk@latest to pull the newest stable version
• Run diagnostics with expo-doctor to detect mismatched dependencies before proceeding
• Clear caches using watchman watch-del-all, rm -rf node_modules, and native clean commands (pod install --repo-update, ./gradlew clean)
• Regenerate native code with npx expo prebuild --clean for bare workflow projects
• Migrate deprecated packages like expo-av to expo-audio/expo-video and remove legacy configuration files
• Enable modern features including React Compiler and react-native-worklets for SDK 54+ compatibility

Frequently Asked Questions

What is the first step when upgrading Expo SDK in a plugin?

Start with npx expo install expo@latest followed by npx expo install --fix to align peer dependencies. Immediately run npx expo-doctor to detect mismatched versions or missing native modules before you attempt any native builds.

When should I use npx expo prebuild --clean?

Use this command when working in a bare workflow after upgrading any package that modifies native code. The --clean flag regenerates the ios/ and android/ directories from scratch, ensuring native project files match the upgraded SDK requirements.

How do I handle deprecated packages like expo-av after an upgrade?

Replace expo-av with the split packages expo-audio and expo-video. Update all imports in your source code and remove any references to the old package from package.json. This migration is required for SDK 53+ to prevent runtime errors from removed APIs.

Why is cache clearing necessary during SDK upgrades?

Metro, Watchman, and native build systems cache compiled artifacts and dependency trees. Stale caches can cause "module not found" errors or link against old native binaries even after package.json updates. Clearing caches with watchman watch-del-all, rm -rf node_modules .expo, and native clean commands guarantees a fresh state.

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