upgrading-react-native

interface:
  display_name: "Upgrade React Native"
  short_description: "React Native upgrade workflow updated templates, dependencies, and common pitfalls"
  default_prompt: "Use $upgrading-react-native to plan and execute a React Native upgrade."

title: Expo SDK Upgrade Layer
impact: HIGH
tags: expo, sdk, react-native, dependencies

Skill: Expo SDK Upgrade Layer

Expo-specific add-on to the core Upgrade Helper workflow. Use only when expo exists in app package.json.

Quick Commands

npm pkg get dependencies.expo devDependencies.expo --prefix "$APP_DIR"
cd "$APP_DIR" && npx expo install --fix
cd "$APP_DIR" && npx expo-doctor

When to Apply

• expo or expo-updates is present in the target app package
• RN upgrade is paired with Expo SDK upgrade

Official Expo Reference

• Follow Expo's official upgrade skill as a primary guide:
  • Expo Upgrading Expo Skill
• Important for this workflow: skip app.json changes, because this is not an Expo Managed project.

Pre-Upgrade Audit (Required)

• Confirm SDK version and target path.
• Inventory dependencies and native modules.
• Review config plugins and prebuild behavior.
• Review native build setup (Gradle, iOS settings, CI/EAS config).
• Identify critical app flows for regression testing before changes.

Workflow Additions

1. Run Expo compatibility alignment.
   • npx expo install --fix (source of truth for SDK-compatible versions).
   • Treat expo-modules package versions as SDK-coupled; align them with Expo recommendations.
2. Run health checks.
   • npx expo-doctor; resolve blocking issues first.
3. If native folders are part of workflow, reconcile prebuild output.
   • npx expo prebuild --clean (when applicable).
4. Handle React 19 pairing.
   • Run react.md.
5. Run upgrade-verification.md for manual or agent-assisted regression checks and release gates.

Notes

• Use npx expo ...; do not require global expo-cli.
• Some package bumps may be optional if not SDK-bound; validate before deferring.
• Read Expo and React Native release notes deeply before editing code, then map each breaking change to a concrete code/task item.

Related Skills

• upgrading-react-native.md - Routing and mode selection
• upgrade-helper-core.md - Base upgrade workflow
• react.md - React and React 19 alignment
• upgrade-verification.md - Post-upgrade validation, including agent-device-assisted checks
• monorepo-singlerepo-targeting.md - Repo/app selection and command scoping

title: Monorepo vs Single-App Targeting
impact: HIGH
tags: monorepo, workspace, react-native, app-selection

Skill: Monorepo vs Single-App Targeting

Small instruction set for selecting the correct app package and running upgrade commands in the right scope.

Quick Commands

APP_DIR=apps/mobile
npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"

Rules

1. Pick one target app package before any upgrade command.
2. Run all app-specific commands with --prefix "$APP_DIR" or from cd "$APP_DIR".
3. Use APP_DIR=. for single-package repos.
4. Never apply diffs to workspace root when RN app lives in a subpackage.

Verification

• react-native is present in APP_DIR/package.json.
• ios/ and android/ paths used for build/pods are under APP_DIR.

Related Skills

• upgrading-react-native.md - Routing and mode selection
• upgrade-helper-core.md - Base upgrade workflow
• expo-sdk-upgrade.md - Expo-specific steps

title: React Upgrade Layer
impact: HIGH
tags: react, react-19, rntl, types

Skill: React Upgrade Layer

React-specific upgrade rules to run when react changes during a React Native or Expo upgrade.

When to Apply

• react version changes (major, minor, or patch).
• React Native target implies a newer React pairing.
• Tests/types break after React upgrade.

React Pairing Rules

1. Keep companion packages aligned with installed React version:
   • react-test-renderer
   • @types/react
   • react-dom (if used by the app)
2. Prefer matching React major and minor exactly; patch should also match when available.
3. Do not leave these packages on older x.y after upgrading react.

React 19 Rules

1. Upgrade @testing-library/react-native to v13+.
2. Follow:
   • Expo React 19 Reference
   • RNTL LLM Docs
3. Expect type-level breakages from deprecated API removals; fix code and mocks accordingly.

Related Skills

• upgrade-helper-core.md - Core RN upgrade workflow
• upgrading-dependencies.md - Dependency compatibility triage
• expo-sdk-upgrade.md - Expo-specific upgrade layer
• upgrade-verification.md - Post-upgrade validation, including agent-device-assisted checks

title: Upgrade Helper Core Workflow
impact: HIGH
tags: react-native, upgrade-helper, rn-diff-purge, ios, android

Skill: Upgrade Helper Core Workflow

Reliable, framework-agnostic workflow for React Native upgrades using Upgrade Helper and rn-diff-purge.

Run shared environment checks first in upgrading-react-native.md under Prerequisites (All Upgrade Paths).

Quick Commands

npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest
curl -L "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES"
curl -L -o /tmp/rn-diff-<current_version>..<target_version>.diff "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff"
grep -n "^diff --git" /tmp/rn-diff-<current_version>..<target_version>.diff

Upgrade Helper API (Inline Reference)

• List supported versions:
  • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
• Fetch raw unified diff:
  • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff
• GitHub compare view:
  • https://github.com/react-native-community/rn-diff-purge/compare/release/<current_version>..release/<target_version>
• Upgrade Helper UI:
  • https://react-native-community.github.io/upgrade-helper/?from=<current_version>&to=<target_version>
• Path mapping note:
  • Diff paths are prefixed with RnDiffApp/; remap to your app paths and package names.

Inputs

• APP_DIR: app package path (. for single-package repos)
• current_version: current React Native version
• target_version: target React Native version (latest by default)

Reliable Workflow

1. Detect app and versions.
   • Read react-native from APP_DIR/package.json.
   • Resolve target via npm view react-native dist-tags.latest unless user provides one.
2. Validate target_version exists.
   • Check RELEASES from rn-diff-purge and confirm target_version is listed.
   • If missing, stop and ask user to choose one of available versions.
3. Collect canonical sources.
   • Upgrade Helper URL.
   • rn-diff-purge raw diff.
4. Fetch diff with fallback.
   • Try exact raw diff: <current_version>..<target_version>.
   • If 404, try nearest available patch versions and report what was attempted.
   • If no available pair works, stop and ask user for target adjustment.
5. Build dependency baseline from rn-diff-purge first.
   • Start with the RnDiffApp/package.json diff for the exact version pair.
   • Do not manually install RN packages one-by-one before this baseline is captured.
6. Publish a short execution plan before edits.
   • Include ordered phases: dependency baseline, one-pass install, native/tooling merges, verification.
   • If dependency migrations are ambiguous, ask for user confirmation before modifying package choices.
7. Run dependency risk planning.
   • Use upgrading-dependencies.md.
   • Fold approved migrations into the same dependency update pass.
8. Apply dependency updates in one pass.
   • Update APP_DIR/package.json (and lockfile) from the baseline plus approved migrations.
   • Run exactly one install command with the repo's package manager (npm install, yarn install, pnpm install, or bun install).
   • Avoid piecemeal installs such as repeated npm install <pkg> unless explicitly requested.
9. Build a change checklist from diff.
   • Group by JS/TS, iOS, Android, tooling.
   • Skip template-only UI (App.tsx) unless explicitly requested.
   • Skip template-only dependencies (@react-native/new-app-screen) unless they exist in the app.
10. Apply diff safely.

• Treat RnDiffApp as placeholder; remap app/package names.
• Merge, do not overwrite project-specific customizations.

11. Sync native deps.

• Run iOS pods in APP_DIR/ios.

12. Validate and gate completion.

• iOS build passes.
• Android build passes.
• tests/typecheck/lint pass or failures are documented with next actions.
• If react was upgraded, run react.md.
• If target_version >= 0.81 and tests fail due to missing modules, add proper mocks.
  • Example (BackHandler mock removal): https://github.com/facebook/react-native/issues/52667#issuecomment-3094788618
• Run upgrade-verification.md before closing the upgrade.

Stop Conditions

• Missing react-native dependency in target package.
• Diff source unavailable and no fallback available.
• Unresolved native merge conflicts in iOS/Android entry files.

Reliability Rules

• Keep operations version-pair scoped (current_version -> target_version).
• Prefer official sources over ad-hoc guides.
• Record every manual deviation from Upgrade Helper.
• Do not run Expo-specific commands here.

Common Pitfalls

• Upgrading an Expo project with only RN CLI steps: apply the Expo layer (expo-sdk-upgrade.md).
• Skipping the Upgrade Helper: leads to missed native config changes.
• Treating RnDiffApp paths as literal project paths.
• Copying the entire template wholesale: use the diff as a guide and merge only needed changes.
• Using the wrong changelog: 0.7x changes live in CHANGELOG-0.7x.md.
• Running the wrong package manager: always match the repo lockfile.
• Forgetting CocoaPods: iOS builds will fail without pod install.
• Not updating Android Gradle wrapper binary: update android/gradle/wrapper/gradle-wrapper.jar for the target RN version. Source template:
  • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/release/<target_version>/RnDiffApp/android/gradle/wrapper/gradle-wrapper.jar
• Flipper artifacts lingering after removal in v0.74: remove ReactNativeFlipper.kt and FLIPPER_VERSION when the target RN version drops Flipper.
• Skipping platform rebuilds after Pod/Gradle changes.

Related Skills

• upgrading-react-native.md - Routing and mode selection
• upgrading-dependencies.md - Dependency compatibility and migration plan
• expo-sdk-upgrade.md - Expo-only layer on top of core workflow
• react.md - React and React 19 alignment
• upgrade-verification.md - Post-upgrade validation, including agent-device-assisted checks
• monorepo-singlerepo-targeting.md - Repo/app selection and command scoping

title: Upgrade Verification
impact: HIGH
tags: verification, regression, android, ios, navigation

Skill: Upgrade Verification

Manual and agent-assisted validation checklist after React Native and/or Expo upgrades.

Scope

• Focus on behavior and UX regressions that static diffs cannot prove.
• Keep checks small, repeatable, and tied to critical user flows.

Agent-Assisted Checks

Use agent-device for runnable app verification. If it is missing and device verification is needed, install it through the environment's approved/trusted path or ask the user to install or enable it.

1. If the agent environment exposes an agent-device skill, read it before planning exact commands.
2. If the agent-device CLI is available, follow its agent-device help workflow guidance.
3. Open or install the upgraded app, drive each critical scenario, and verify with UI snapshots.
4. Capture screenshots, logs, and pass/fail evidence for changed flows.
5. Fall back to human validation for credentials, physical-device-only hardware, or profiler surfaces the agent cannot inspect.

Behavior Checks (Required)

1. App launch and core journeys work on both iOS and Android.
2. Navigation behavior is correct (forward/back stack, params, deep links, modal flows).
3. Android edge-to-edge is visually correct (status bar, nav bar, safe area insets, keyboard overlays).
4. Permissions and device APIs work (camera, location, notifications, file/media access).
5. Background/restore paths work (app resume, push open, interrupted flows).

Build and Test Gates

1. Run unit/integration tests and fix all upgrade-related failures.
2. If target_version >= 0.81 and tests fail due to missing modules, add proper mocks.
   • Example (BackHandler mock removal): https://github.com/facebook/react-native/issues/52667#issuecomment-3094788618
3. Build installable artifacts for both platforms.
4. For Expo apps, run npx expo-doctor from expo-sdk-upgrade.md.

Evidence to Capture

• Screen recordings/screenshots for changed flows.
• List of verified scenarios and pass/fail status.
• Follow-up fixes for any observed regressions.

Related Skills

• upgrading-react-native.md - Upgrade workflow router
• upgrade-helper-core.md - Core RN diff/merge workflow
• expo-sdk-upgrade.md - Expo-specific checks and commands
• react.md - React-specific upgrade rules

title: Upgrading Dependencies
impact: HIGH
tags: react-native, dependencies, compatibility, migration

Skill: Upgrading Dependencies

Common dependency issues and mitigations when upgrading React Native.

Quick Checks

npm ls --depth=0

Dependency Risk and Migration Plan

1. Review compatibility signals:
   • RN nightly tests
   • React Native Directory
2. If react is upgraded, run react.md for companion package alignment and React 19 rules.
3. Handle known risky packages:
   • react-native-fast-image -> prefer @d11/react-native-fast-image or expo-image (confirm with user)
   • @react-native-cookies/cookies -> prefer @preeternal/react-native-cookie-manager (confirm with user)
   • react-native-code-push -> treat as incompatible; disable for upgrade and consider @appzung/react-native-code-push, @bravemobile/react-native-code-push, or expo-updates
   • react-native-image-crop-picker -> upgrade to >=0.51.1; if unstable, plan migration to expo-image-picker (confirm with user)
   • react-native-network-logger - lists react and react-native in peer deps as * which can be misleading. Upgrade to v2 if target_version >= 0.79.
   • react-native-permissions - upgrade to v5 if possible (requires RN 0.74+)
4. Apply additional cleanup rules:
   • If @rnx-kit/metro-resolver-symlinks is present, remove it from deps and metro.config.js (Metro supports symlinks since 0.72)
   • If app uses react-native-localize timezone APIs and @callstack/timezone-hermes-fix is missing, ask whether to add it
5. If no safe alternative is found for a critical dependency, ask for explicit user confirmation before continuing.
6. Read only breaking/manual steps from RN blog posts between current_version and target_version.

Related Skills

• upgrade-helper-core.md - Core upgrade workflow
• react.md - React and React 19 alignment
• expo-sdk-upgrade.md - Expo-specific dependency alignment
• upgrading-react-native.md - Routing and mode selection

title: Upgrading React Native
impact: HIGH
tags: react-native, upgrade, routing

Skill: Upgrading React Native

Router for React Native upgrade workflows. Start with core Upgrade Helper instructions, then apply focused add-ons by project shape.

Prerequisites (All Upgrade Paths)

• Ensure the repo is clean or on a dedicated upgrade branch.
• Know which package manager the repo uses (npm, yarn, pnpm, bun).
• Use Node.js 20.19.4+, Java 17, and Xcode 16.4+ (with Command Line Tools), following https://reactnative.dev/docs/set-up-your-environment.
  • Optional: use Xcodes to manage Xcode versions.
• Verify active versions before upgrading: node -v, java -version.
• Verify Android Studio is installed.
• For iOS, verify Xcode CLI toolchain is in sync (common pitfall after Xcode upgrades):
  • Check:
    • xcode-select --print-path
    • xcodebuild -version
    • xcrun --sdk iphoneos --show-sdk-version
  • If mismatch is suspected, re-point and initialize:
    • sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
    • sudo xcodebuild -runFirstLaunch

Quick Start

0. Run the Prerequisites (All Upgrade Paths) (#prerequisites-all-upgrade-paths) checklist.
1. Set APP_DIR to the app folder (. for single-app repos).
2. Use monorepo-singlerepo-targeting.md if you need help choosing APP_DIR.
3. Run upgrade-helper-core.md first to anchor changes to rn-diff-purge.
4. Publish a short plan (ordered phases) before making versioned edits.
5. Run upgrading-dependencies.md to assess risky packages and migrations.
6. Apply dependency updates in one pass and run a single install with the repo package manager.
7. Run react.md when react is upgraded.
8. Add expo-sdk-upgrade.md only if expo is present in APP_DIR/package.json.
9. Finish with upgrade-verification.md.

Decision Map

• Need canonical RN diff/merge workflow: upgrade-helper-core.md
• Need to ensure dependencies are compatible: upgrading-dependencies.md
• Need React and React 19 alignment: react.md
• Project contains Expo SDK deps: expo-sdk-upgrade.md
• Need manual or agent-assisted post-upgrade validation: upgrade-verification.md

Related Skills

• native-platform-setup.md (../../react-native-best-practices/references/native-platform-setup.md) - Tooling and native dependency basics
• native-android-16kb-alignment.md (../../react-native-best-practices/references/native-android-16kb-alignment.md) - Third-party library alignment for Google Play