upgrading-expo

Name: upgrading-expo
Author: Expo Team

ExpoSDK upgradeReact Nativedependency managementmobile developmenttroubleshootingnative modulesapp maintenance

⭐ 2.1k📄 MIT🕒 2026-06-16Source ↗

Install this skill

npx skills add expo/skills

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

Upgrading an Expo project requires a systematic approach to update dependencies, align native configurations, and adapt to breaking changes introduced in newer SDK versions. This skill orchestrates the version migration process by executing automated package updates, running diagnostic checks with expo-doctor, and managing native directory synchronization. It addresses structural modifications such as transitioning to the New Architecture, adopting React 19 standards, and enabling the React Compiler. The process includes cleanup tasks like removing redundant configuration files and migrating deprecated libraries to their current counterparts. By automating cache clearing and ensuring native modules are rebuilt properly, this skill helps stabilize the development environment, prevents runtime errors stemming from stale build artifacts, and ensures the application adheres to current Expo best practices and performance standards.

When to Use This Skill

•Updating a project from one Expo SDK version to the next
•Resolving native module build failures after a version bump
•Migrating legacy projects to use the New Architecture
•Optimizing project configuration by removing obsolete Babel and Metro settings

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“update my expo project to the latest sdk
“fix my expo dependencies after upgrading
“migrate my expo app to sdk 54
“how do i clean up my expo project after a version upgrade
“run a full expo diagnostic and update

Pro Tips

💡Before initiating any major upgrade, always commit your current working changes and consider creating a dedicated Git branch. This provides a safe rollback point if unexpected issues arise.
💡Thoroughly review the official Expo release notes for your target SDK version beforehand, paying close attention to 'Breaking Changes' and 'Known Issues' sections.
💡When using `npx expo prebuild --clean`, be mindful. If your project contains custom native code in the `ios` or `android` directories not managed by Expo config plugins, ensure you back it up first.

What this skill does

•Automated dependency synchronization via expo install
•Environment diagnostics and configuration validation
•Native project directory regeneration with prebuild
•Cleanup of legacy build caches and temporary files
•Integration of modern build features like React Compiler

When not to use it

✕Downgrading an Expo SDK version
✕Debugging specific application-level code logic errors

Example workflow

Run npx expo install expo@latest to update core packages
Execute npx expo install --fix to resolve version mismatches
Perform diagnostic checks using npx expo-doctor
Clear project caches including node_modules and platform-specific build folders
Rebuild native directories with npx expo prebuild --clean
Verify functionality through local development environment testing

Prerequisites

–A functional local development environment
–Git repository initialized for tracking changes
–Node.js version compatible with the target SDK

Pitfalls & limitations

!Failure to check release notes for specific breaking API changes
!Incompatibility with third-party native modules not yet supporting the target SDK
!Forgetting to update patches in the patches directory

FAQ

Do I still need to set newArchEnabled in app.json?

No, as of SDK 53, the New Architecture is enabled by default and the configuration flag is no longer required.

What should I do with my old expo-av imports?

Migrate your implementation to the individual expo-audio and expo-video packages, as expo-av is deprecated.

When should I delete my metro.config.js?

You can safely remove it if it only contains default Expo configurations, as these are now handled automatically.

Is the React Compiler ready for production use?

Yes, starting in SDK 54, the React Compiler is considered stable and is recommended for improved performance.

How it compares

Unlike manual package management which often leaves behind stale caches and conflicting legacy configurations, this skill follows the official Expo upgrade lifecycle to ensure full environment consistency.

Source & trust

⭐ 2.1k stars📄 MIT🕒 Updated 2026-06-16

View original skill on GitHub →

📄 Full skill instructions — original source: expo/skills

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

## Step-by-Step Upgrade Process

1. Upgrade Expo and dependencies

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

2. Run diagnostics: npx expo-doctor

3. 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

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

- 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 Package | Replacement |
| -------------------- | ---------------------------------------------------- |
| expo-av | expo-audio and expo-video |
| expo-permissions | Individual package permission APIs |
| @expo/vector-icons | expo-symbols (for SF Symbols) |
| AsyncStorage | expo-sqlite/localStorage/install |
| expo-app-loading | expo-splash-screen |
| expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |

## 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.
- 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](https://docs.expo.dev/router/migrate/from-expo-webpack/).

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

By Expo Team

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/upgrading-expo/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/expo/skills/upgrading-expo/SKILL.md
Cursor: ~/.cursor/skills/expo/skills/upgrading-expo/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/expo/skills/upgrading-expo/SKILL.md

🚀 Install with CLI:
npx skills add expo/skills

Read the Master Guide: Mastering Agent Skills →

Recommended Rules

View more rules →

Recommended Workflows

View more workflows →

Nuke & Reinstall

npmTroubleshootingDependencies

--- description: The nuclear option for when dependencies are completely broken --- 1. **Remove node_modules**: - Delete the existing `node_module...

Debug Module Not Found Errors

Node.jsDebuggingDependencies

--- description: Systematically resolve "Cannot find module" errors --- 1. **Check the Import Path**: - ❌ `import { foo } from '../components/Foo'...

Debug 'Module Not Found' After Git Pull

DebuggingGitDependencies

--- description: Fix dependency issues after pulling changes from Git --- 1. **Clear Node Modules Cache**: - Remove cached modules and reinstall. ...

Recommended MCP Servers

View more MCP servers →

Dataverse DevTools MCP Server

Community

An MCP server exposing ready-to-use Dataverse/Dynamics 365 tools for user and security administration, data operations, Web API executions, metadata exploration, and troubleshooting.