Expo SDK upgrades
Use this path for apps with an expo dependency, including React Native apps that use
Expo modules while maintaining their native projects manually.
Establish the target and workflow
- Read the app workspace's package.json, lockfile, Expo app config, build scripts, config plugins, and native-project documentation. Record the current Expo, React, and React Native versions, package manager, supported platforms, and existing local edits.
- Resolve the requested SDK against its current release notes and versioned documentation. With no target, resolve the latest stable SDK; use previews only when requested. If the user supplied an RN version, establish which SDK supports it. If none does, explain the incompatibility and ask for a target decision before changing dependencies.
- Plan incremental SDK upgrades, unless current release notes prescribe a different route for an affected version. Check minimum patch versions and required toolchain versions. Do not retain a fixed latest-version number or a permanent list of migrations here.
- Establish native ownership per platform: generated through Continuous Native Generation (CNG), manually maintained, or mixed. Inspect config plugins, ignored/tracked files, project docs, and native customizations. Presence or absence of a directory alone is insufficient evidence. Preserve edits; ask when ownership cannot be established.
Summarize the target, upgrade sequence, affected modules, and native migration approach before edits. Proceed within an already approved upgrade scope; resolve only outstanding target or native-ownership decisions.
Apply each SDK step
- Install the explicit Expo version selected for this step using the repo's package manager
in the app workspace. Update its existing lockfile. Do not use an unqualified
latestduring a pinned or intermediate upgrade. - Run
npx expo install --fix, thennpx expo-doctor(or the repo's equivalent runner). Let the selected SDK align React, React Native, and Expo package versions. Review the changes and resolve diagnostics before advancing; retain intentionally pinned exceptions only with compatibility evidence for this SDK. - Read release notes and migration guides for packages actually used: Router/navigation, audio/video, animation/worklets, custom native modules, and development clients. Update consumers before removing replaced dependencies. Check required peers, install exclusions, patches, and config plugins individually; retain those still needed. Do not turn an SDK upgrade into an unrelated compiler, navigation, or architecture migration.
- CNG: when regeneration is necessary, confirm customizations are reproducible from
app config/plugins and inspect native diffs first. Use the project's generation/build
workflow.
prebuild --cleanreplaces native directories: never run it over unpreserved manual changes. Missing directories can be generated by the project's normal build. - Manually maintained native projects: apply relevant changes from Expo's native project upgrade helper and SDK release notes, preserving integrations. Install iOS pods when applicable. Do not run clean prebuild or replace native files with an RN template diff. For mixed ownership, limit generation to the verified generated platform.
- Reset only caches implicated by an actual failure. Avoid blanket deletion of dependencies, lockfiles, native projects, or global Watchman watches as a routine upgrade step.
Verify and report
Run the repo's formatter, typecheck, relevant tests, and Expo diagnostics. Build the supported native targets with the new dependencies and rebuild development clients as needed; check web too if shipped. Exercise startup, navigation, and affected device integrations. A passing export or doctor run alone is not evidence that native code builds or behaves correctly. Give builds, installs, and tests hard deadlines according to the project instructions.
Report versions, native/config changes, validation actually performed, and remaining blockers. Update existing versioned Expo documentation links when appropriate. Do not publish EAS updates, submit store builds, or send upstream feedback as part of this local upgrade.
Sources and migration references
Consult these at execution time; load only migration references relevant to the chosen SDK and installed modules:
- Expo SDK upgrade walkthrough
- SDK release notes
- Continuous Native Generation
- Native project upgrade helper
- Expo's expo-upgrade skill and migration references
Adapted from the workflow ideas in Expo's MIT-licensed skill, with project-specific target
selection and native-ownership checks. Retrieve GitHub files with gh where available.