AutoGineer
Generated banner for Upgrading Expo
Generated logo for Upgrading Expo

Upgrading Expo

OpenAIOfficialCreated by Expo TeamDistributed by OpenAI

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Guidelines for upgrading Expo SDK versions and fixing dependency issues
— the description by Expo Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured process for upgrading Expo projects to newer SDK versions. It covers dependency management, diagnostic checks, native project regeneration, and critical migration paths for deprecated packages like expo-av. It also includes configuration best practices for modern Expo features such as the React Compiler, Hermes v1, and the New Architecture.

What it does

  • Provides a step-by-step procedure for upgrading Expo SDK and dependencies.
  • Offers diagnostic commands to verify project health after upgrades.
  • Details the migration process for replacing expo-av with expo-audio and expo-video.
  • Outlines configuration changes for app.json and project housekeeping.
  • Explains how to handle native directory regeneration for projects using prebuild.
  • Lists common breaking changes and deprecated packages to watch for during upgrades.

When to use it

  • When preparing to upgrade an existing Expo project to a newer SDK version.
  • When troubleshooting dependency conflicts after an SDK update.
  • When migrating from deprecated libraries like expo-av to newer alternatives.
  • When configuring new project features like the React Compiler or Hermes v1.
  • When cleaning up project caches and native build artifacts.

Advantages

  • Reduces manual effort by providing a clear, repeatable upgrade checklist.
  • Centralizes migration paths for major breaking changes.
  • Helps maintain project stability by identifying necessary native directory updates.
  • Promotes best practices for modern Expo development and configuration.

Usage examples

“How do I upgrade my Expo project to the latest SDK version?”
The agent will guide you through running 'npx expo install expo@latest', fixing dependencies, running 'expo-doctor', and clearing caches.
“I need to migrate my audio code from expo-av to expo-audio.”
The agent will provide the mapping of old methods to new hooks like 'useAudioPlayer' and 'useAudioRecorder'.
“How do I regenerate my native directories after an upgrade?”
The agent will instruct you to use 'npx expo prebuild --clean' if your project is not a bare workflow app.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/openai/upgrading-expo/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip upgrading-expo.zip -d .agents/skills

Documentation by Expo Team

References

  • ./references/new-architecture.md -- SDK +53: New Architecture migration guide

  • ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)

  • ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide

  • ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.*)

  • ./references/expo-av-to-audio.md -- Migrate audio playback and recording from expo-av to expo-audio

  • ./references/expo-av-to-video.md -- Migrate video playback from expo-av to expo-video

Beta/Preview Releases

Beta versions use .preview suffix (e.g., 55.0.0-preview.2), published under @next tag.

Check if latest is beta: https://exp.host/--/api/v2/versions (look for -preview in expoVersion)

npx expo install expo@next --fix  # install beta

Step-by-Step Upgrade Process

  1. Upgrade Expo and dependencies

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

  1. Run diagnostics: npx expo-doctor

  2. Clear caches and reinstall

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

Breaking Changes Checklist

  • Check for removed APIs in release notes

  • Update import paths for moved modules

  • Review native module changes requiring prebuild

  • Test all camera, audio, and video features

  • Verify navigation still works correctly

Prebuild for Native Changes

First check if ios/ and android/ directories exist in the project. If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.

If upgrading requires native changes:

npx expo prebuild --clean

This regenerates the ios and android directories. Ensure the project is not a bare workflow app before running this command.

Clear caches for bare workflow

These steps only apply when ios/ and/or android/ directories exist in the project:

  • Clear the cocoapods cache for iOS: cd ios && pod install --repo-update

  • Clear derived data for Xcode: npx expo run:ios --no-build-cache

  • Clear the Gradle cache for Android: cd android && ./gradlew clean

Housekeeping

  • Review release notes for the target SDK version at https://expo.dev/changelog

  • If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.

  • Enable React Compiler in SDK 54+ by adding "experiments": { "reactCompiler": true } to app.json — it's stable and recommended

  • Delete sdkVersion from app.json to let Expo manage it automatically

  • Remove implicit packages from package.json: @babel/core, babel-preset-expo, expo-constants.

  • If the babel.config.js only contains 'babel-preset-expo', delete the file

  • If the metro.config.js only contains expo defaults, delete the file

Deprecated Packages

Old PackageReplacement
expo-avexpo-audio and expo-video
expo-permissionsIndividual package permission APIs
@expo/vector-iconsexpo-symbols (for SF Symbols)
AsyncStorageexpo-sqlite/localStorage/install
expo-app-loadingexpo-splash-screen
expo-linear-gradientexperimental_backgroundImage + CSS gradients in View

When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.

expo.install.exclude

Check if package.json has excluded packages:

{
  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
}

Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.

Removing patches

Check if there are any outdated patches in the patches/ directory. Remove them if they are no longer needed.

Postcss

  • autoprefixer isn't needed in SDK +53. Remove it from dependencies and check postcss.config.js or postcss.config.mjs to remove it from the plugins list.

  • Use postcss.config.mjs in SDK +53.

Metro

Remove redundant metro config options:

  • resolver.unstable_enablePackageExports is enabled by default in SDK +53.

  • experimentalImportSupport is enabled by default in SDK +54.

  • EXPO_USE_FAST_RESOLVER=1 is removed in SDK +54.

  • cjs and mjs extensions are supported by default in SDK +50.

  • Expo webpack is deprecated, migrate to Expo Router and Metro web.

Hermes engine v1

Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting useHermesV1: true in the expo-build-properties config plugin, and may require a specific version of the hermes-compiler npm package. Hermes v1 will become a default in some future SDK release.

New Architecture

The new architecture is enabled by default, the app.json field "newArchEnabled": true is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.

Files

references/react-19.md

React 19

React 19 is included in Expo SDK 54. This release simplifies several common patterns.

Context Changes

useContext → use

The use hook replaces useContext:

// Before (React 18)
import { useContext } from "react";
const value = useContext(MyContext);

// After (React 19)
import { use } from "react";
const value = use(MyContext);

  • The use hook can also read promises, enabling Suspense-based data fetching.

  • use can be called conditionally, this simplifies components that consume multiple contexts.

Context.Provider → Context

Context providers no longer need the .Provider suffix:

// Before (React 18)
<ThemeContext.Provider value={theme}>
  {children}
</ThemeContext.Provider>

// After (React 19)
<ThemeContext value={theme}>
  {children}
</ThemeContext>

ref as a Prop

Removing forwardRef

Components can now receive ref as a regular prop. forwardRef is no longer needed:

// Before (React 18)
import { forwardRef } from "react";

const Input = forwardRef<TextInput, Props>((props, ref) => {
  return <TextInput ref={ref} {...props} />;
});

// After (React 19)
function Input({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
  return <TextInput ref={ref} {...props} />;
}
Migration Steps

  1. Remove forwardRef wrapper

  2. Add ref to the props destructuring

  3. Update the type to include ref?: React.Ref<T>

Other React 19 Features

  • Actions — Functions that handle async transitions

  • useOptimistic — Optimistic UI updates

  • useFormStatus — Form submission state (web)

  • Document Metadata — Native <title> and <meta> support (web)

Cleanup Checklist

When upgrading to SDK 54:

  • [ ] Replace useContext with use

  • [ ] Remove .Provider from Context components

  • [ ] Remove forwardRef wrappers, use ref prop instead

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Expo Team
Publisher
OpenAI (Official)
Distributed by
OpenAI
Source
openai/plugins · plugins/expo/skills/upgrading-expo · commit d420d13
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from plugins/expo/LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Expo Team or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download upgrading-expo.zip