upgrading-react-native

Upgrading React Native

Overview

Covers the full React Native upgrade workflow: template diffs via Upgrade Helper, dependency updates, Expo SDK steps, and common pitfalls.

Typical Upgrade Sequence

1. Route: Choose the right upgrade path via upgrading_react_native.md
2. Diff: Fetch the canonical template diff using Upgrade Helper via upgrade_helper_core.md
3. Dependencies: Assess and update third-party packages via upgrading_dependencies.md
4. React: Align React version if upgraded via react.md
5. Expo (if applicable): Apply Expo SDK layer via expo_sdk_upgrade.md
6. Verify: Run post-upgrade checks via upgrade_verification.md

# Quick start: detect current version and fetch diff
npm pkg get dependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest

# Example: upgrading from 0.76.9 to 0.78.2
# 1. Fetch the template diff
curl -L -f -o /tmp/rn-diff.diff \
  "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.76.9..0.78.2.diff" \
  && echo "Diff downloaded OK" || echo "ERROR: diff not found, check versions"
# 2. Review changed files
grep -n "^diff --git" /tmp/rn-diff.diff
# 3. Update package.json, apply native changes, then install + rebuild
npm install --prefix "$APP_DIR"
cd "$APP_DIR/ios" && pod install
# 4. Validate: both platforms must build successfully
npx react-native build-android --mode debug --no-packager
xcodebuild -workspace "$APP_DIR/ios/App.xcworkspace" -scheme App -sdk iphonesimulator build

When to Apply

Reference these guidelines when:

• Moving a React Native app to a newer version
• Reconciling native config changes from Upgrade Helper
• Validating release notes for breaking changes

Quick Reference

File	Description
upgrading_react_native.md	Router: choose the right upgrade path
upgrade_helper_core.md	Core Upgrade Helper workflow and reliability gates
upgrading_dependencies.md	Dependency compatibility checks and migration planning
react.md	React and React 19 upgrade alignment rules
expo_sdk_upgrade.md	Expo SDK-specific upgrade layer (conditional)
upgrade_verification.md	Manual post-upgrade verification checklist
monorepo_singlerepo_targeting.md	Monorepo and single-repo app targeting and command scoping

Problem → Skill Mapping

Problem	Start With
Need to upgrade React Native	upgrade_helper_core.md
Need dependency risk triage and migration options	upgrading_dependencies.md
Need React/React 19 package alignment	react.md
Need workflow routing first	upgrading_react_native.md
Need Expo SDK-specific steps	expo_sdk_upgrade.md
Need manual regression validation	upgrade_verification.md
Need repo/app command scoping	monorepo_singlerepo_targeting.md