upgrading-expo

Overview of upgrading-expo skill

What the upgrading-expo skill does

The upgrading-expo skill helps you plan and execute Expo SDK upgrades with fewer blind spots than a generic “how do I upgrade Expo?” prompt. It is focused on the real work: updating core packages, fixing dependency drift, clearing stale caches, and catching common breaking changes around React, the New Architecture, native tabs, and expo-av migrations.

Who should use upgrading-expo

This upgrading-expo skill is best for frontend developers, React Native teams, and AI agents maintaining an existing Expo app. It is most useful when you already have a project and need a practical upgrade path, not just release-note summaries.

Best-fit cases:

• Upgrading between recent Expo SDK versions
• Fixing install or runtime breakage after expo install --fix
• Migrating away from changed or split packages like expo-av
• Checking whether SDK-specific changes such as React 19 or Native Tabs affect your codebase

The real job to be done

Users evaluating upgrading-expo for Frontend Development usually want answers to three questions fast:

1. What command sequence should I run first?
2. Which breaking changes are likely to hit my app?
3. What files or patterns should I inspect before I waste time debugging?

This skill is valuable because it bundles those decisions into one place and links them to concrete migration references.

What makes it different from a generic upgrade prompt

A normal prompt can suggest “upgrade Expo and run doctor.” The upgrading-expo skill goes further by surfacing version-linked migration topics from the repository, including:

• New Architecture defaults in SDK 53+
• React 19 changes in SDK 54
• React Compiler setup in SDK 54+
• Native Tabs API changes in SDK 55
• expo-av replacement paths for audio and video

That makes it better for targeted upgrade work than a broad React Native troubleshooting prompt.

What to know before installing

This skill is guidance-heavy rather than automation-heavy. It does not ship scripts that inspect your repo for you. Its value comes from the curated upgrade workflow and the reference documents you can apply to your own codebase. If you want a push-button migrator, this is not that. If you want a high-signal upgrade checklist with concrete migration examples, it is a strong fit.

How to Use upgrading-expo skill

Install context for upgrading-expo

If your AI environment supports Skills, install the Expo skills repository and invoke upgrading-expo from there. A common pattern is:

npx skills add https://github.com/expo/skills --skill upgrading-expo

If your toolchain uses a different skill loader, point it at the repo path:
plugins/expo/skills/upgrading-expo

Start with the right repository files

For practical upgrading-expo usage, read these in order:

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

That reading order mirrors the most common upgrade blockers: architecture and React shifts first, feature-level migrations second.

Use the core upgrade sequence first

The skill’s baseline upgrade flow is short and worth following before deeper debugging:

npx expo install expo@latest
npx expo install --fix
npx expo-doctor
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Why this matters:

• expo@latest aligns the SDK
• --fix reconciles Expo-managed package versions
• expo-doctor catches compatibility issues early
• cache clearing removes old Metro/native state that can mimic upgrade bugs

If you are on Linux or do not use Watchman, adapt the cleanup accordingly.

Know when to use preview releases

The skill also documents Expo beta builds via .preview versions under @next. That is useful if you are validating an upcoming SDK or testing a fix that has not landed in stable yet.

npx expo install expo@next --fix

Only do this intentionally. Preview upgrades are not a good default for production apps unless you are explicitly trialing a pre-release.

Provide the inputs the skill actually needs

The best upgrading-expo guide prompts include your current and target state. Give the skill:

• current Expo SDK version
• package manager
• whether you use Expo Go or development builds
• whether you run prebuild
• key packages: expo-router, expo-av, react-native-reanimated, custom native modules
• current errors from install, build, or runtime
• any platform-specific failures on iOS, Android, or web

Without that context, the output will stay generic.

Turn a rough goal into a strong prompt

Weak prompt:

Upgrade my Expo app.

Stronger prompt:

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

Why this works:

• it names the source and target SDK
• it lists high-risk packages
• it asks for prioritized output, not generic advice

Map your app to the reference guides

The repository references are most useful when you deliberately match them to your dependency surface:

• Using expo-av for sound or recording? Read references/expo-av-to-audio.md
• Using expo-av for video? Read references/expo-av-to-video.md
• Upgrading to SDK 55 with expo-router/unstable-native-tabs? Read references/native-tabs.md
• Moving into SDK 53+ or 54+ with native modules? Read references/new-architecture.md
• On SDK 54? Check both references/react-19.md and references/react-compiler.md

This is where the skill provides real information gain over a repo skim.

Watch the highest-risk upgrade areas

In practice, these are the most common break points surfaced by the skill:

• package version misalignment after SDK bump
• New Architecture incompatibility in older native modules
• Reanimated setup changes, including react-native-worklets in SDK 54+
• React 19 API shifts in app or library code
• expo-av migrations to expo-audio and expo-video
• router-level UI changes in Native Tabs

If your app uses any of these, ask the skill to produce a targeted migration checklist rather than a general upgrade summary.

Use a two-pass workflow

A good upgrading-expo usage pattern is:

1. Ask for an upgrade plan based on your versions and dependencies
2. Run the commands
3. Feed back the exact errors and ask for a narrowed remediation plan

This skill is better at structured triage when you bring back concrete output from expo-doctor, TypeScript, Metro, or native builds.

Check release-note style issues the skill implies

The skill’s breaking-changes checklist points to practical review areas:

• removed APIs
• changed import paths
• native module changes requiring prebuild
• camera, audio, and video regressions
• navigation regressions

That means your code review should not stop at package.json. Search your codebase for affected imports and components before you run the app.

Use it carefully with prebuild and native code

If your app uses custom native modules or config plugins, the upgrading-expo skill is still useful, but you should expect extra work outside the markdown references. In those projects, ask the skill to separate:

• JS-only migration tasks
• prebuild regeneration tasks
• native dependency compatibility checks

That separation reduces confusion during upgrades.

upgrading-expo skill FAQ

Is upgrading-expo good for beginners?

Yes, if you already have an Expo project and can share basic project details. It is not a full Expo tutorial. It is an upgrade-focused guide, so beginners get the best results when they provide current SDK version, errors, and major dependencies.

What is the boundary of the upgrading-expo skill?

The skill helps with upgrade planning, command order, and known migration hotspots. It does not automatically inspect your whole repo or guarantee compatibility for every third-party native library. For deep native breakage, you may still need package-specific docs and GitHub issues.

How is upgrading-expo different from just asking an LLM to upgrade Expo?

The main difference is curation. The upgrading-expo skill points the model toward Expo-specific migration references that a generic prompt may miss, especially around expo-av, React 19, React Compiler, Native Tabs, and New Architecture behavior.

When should I not use upgrading-expo?

Skip it if:

• you are starting a brand-new Expo app rather than upgrading one
• your issue is unrelated to SDK upgrades
• you need an automated codemod or CLI migration tool
• your main blocker is a single third-party native library with its own bespoke migration steps

Does upgrading-expo cover preview SDKs?

Yes. The skill notes that beta releases use the .preview suffix and are installed from @next. That is helpful for testing upcoming changes, but stable upgrades remain the safer default.

Is upgrading-expo only for managed workflow apps?

No. It is useful for both managed and prebuild-based Expo apps, but prebuild and custom native code increase the chance that you will need additional manual compatibility checks.

How to Improve upgrading-expo skill

Give the skill your exact version delta

The highest-value improvement is simple: state “from SDK X to SDK Y,” not just “upgrade Expo.” Most migration advice changes materially based on whether you are crossing into SDK 53, 54, or 55.

Include the package surface that changes the answer

For better upgrading-expo results, include the packages that trigger the reference docs:

• expo-av
• expo-router
• react-native-reanimated
• custom native modules
• any package failing expo-doctor

This lets the skill move from generic checklists to likely-impact guidance.

Paste real diagnostics, not paraphrases

Bad:

build failed after upgrade

Better:

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

Exact logs help the skill distinguish dependency drift from API migration issues.

Ask for prioritized output

A strong request format is:

1. commands to run now
2. likely breakages by probability
3. files/imports to search
4. verification steps after fixes

That structure makes the upgrading-expo guide much easier to execute under time pressure.

Separate install failures from code migrations

A common failure mode is mixing package install problems with source-level API changes. Ask the skill to handle them in order:

• dependency alignment
• doctor output
• cache reset
• source migrations
• runtime verification

This reduces circular debugging.

Request codebase-specific search patterns

One of the best ways to improve the upgrading-expo skill output is to ask for grep-style search targets. Example:

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

That converts broad guidance into actionable code review tasks.

Validate the risky paths after the first pass

After the first upgrade attempt, specifically test:

• audio playback and recording
• video playback
• tab navigation
• startup on Expo Go vs dev build
• any screen using heavy animation or native modules

These are the areas most likely to surface SDK transition issues covered by the skill.

Iterate with narrower follow-up prompts

Do not ask the skill to solve the whole upgrade repeatedly. Narrow the second prompt:

• “Focus only on React 19 changes in my shared UI package”
• “Focus only on expo-av video migration”
• “Focus only on New Architecture incompatibilities”

Smaller scopes usually produce clearer, more correct remediation steps.