# Rn Upgrade

> Use when upgrading React Native or Expo SDK versions or resolving upgrade-related dependency issues. Detects Expo projects and follows SDK-compatible versions and their native-project workflow.

- Skill: `nielsmadan/rn-upgrade` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add nielsmadan/rn-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nielsmadan/rn-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: nielsmadan (https://skillmd.com/u/nielsmadan)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/nielsmadan/rn-upgrade

---


<!-- Generated from https://github.com/nielsmadan/agentic-coding — edits here are overwritten. -->

# React Native Upgrade Command

Upgrade the application to the requested React Native version or Expo SDK target. Determine the project's workflow before resolving an omitted target to the latest stable release.

## Usage

```
/rn-upgrade 0.76
/rn-upgrade 0.75.4
/rn-upgrade expo <SDK target>
/rn-upgrade          # upgrades to latest stable
```

## Gotchas
- The rn-diff-purge diff reflects a pristine RN template only. Custom native code (modified `MainApplication.kt`, `AppDelegate.swift`) may be silently overwritten because it's not in the diff.
- Standalone RN multi-version jumps (e.g., 0.73 → 0.76) require building and testing at each intermediate version. Expo upgrade sequences follow the SDK release notes instead.

## Instructions

### Choose the upgrade path

Inspect the app workspace's package.json, lockfile, app config, scripts, and native-project
documentation. An `expo` dependency means Expo compatibility must be checked even in an
app with manually maintained native projects; directory presence alone does not identify
the workflow.

- **Expo present:** read [Expo SDK upgrades](references/expo.md) and follow that workflow
  instead of the standalone React Native steps, troubleshooting, and guidelines below.
  Expo determines the compatible React and React Native versions. An explicit RN target
  must first be mapped to a supported Expo SDK; do not independently bump RN to latest.
- **No Expo dependency:** follow the standalone workflow below. Do not add Expo as part
  of a React Native upgrade.

### Standalone React Native

1. **Determine versions:**
   - Check the current React Native version in package.json
   - If $ARGUMENTS is not specified, fetch the latest stable version from https://github.com/facebook/react-native/releases
   - Record: current version = X, target version = Y

2. **Research and validate:**
   - Fetch the release notes for the target version from https://github.com/facebook/react-native/releases/tag/v{target}
   - Use `research-tech` if release notes mention major changes (e.g., New Architecture default, Kotlin/Swift migration)
   - List any breaking changes that affect this project

3. **Fetch the upgrade diff:**
   - Construct the diff URL: `https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/{current}..{target}.diff`
   - Fetch and analyze the diff to understand all required changes
   - If the diff is unavailable, fall back to the Upgrade Helper UI: https://react-native-community.github.io/upgrade-helper/?from={current}&to={target}

4. **Check dependency compatibility:**
   - List all third-party native modules from package.json
   - For each critical dependency, check its GitHub repo releases/changelog for target RN version support:
     - Firebase: https://github.com/invertase/react-native-firebase/releases
     - Navigation: https://github.com/react-navigation/react-navigation/releases
     - Reanimated: https://github.com/software-mansion/react-native-reanimated/releases
     - Gesture Handler: https://github.com/software-mansion/react-native-gesture-handler/releases
     - Custom native modules in the project
   - Flag any library that hasn't released a compatible version yet and recommend: pin, fork, or find alternative

5. **Plan the upgrade:**
   - Create a task list with TaskCreate, broken into phases:
     - Phase 1: Dependency updates (package.json)
     - Phase 2: Android native changes (MainApplication, Gradle, gradle.properties)
     - Phase 3: iOS native changes (AppDelegate, Podfile, Info.plist, .pbxproj)
     - Phase 4: Library-specific migrations
     - Phase 5: Install dependencies and pods
   - Use EnterPlanMode to present the plan to the user for approval before making changes

6. **Execute the upgrade:**
   - Update package.json with new React Native and React versions
   - Update all @react-native/* packages to match the target version
   - Apply native code changes from the diff, preserving:
     - Custom package names/bundle identifiers
     - Third-party SDK integrations (e.g., Firebase, analytics, crash reporting)
     - Custom build configurations
     - Existing native modules
   - Update Gradle wrapper if required by the diff
   - Enable/configure New Architecture if required
   - Install dependencies: `yarn install` (or `npm install`)
   - Install iOS pods: `cd ios && pod install`

7. **Important considerations:**
   - ALWAYS preserve custom native code integrations
   - Replace template package names (e.g., com.helloworld) with the project's actual package names
   - Check for react-native-fast-image compatibility (may need @d11/react-native-fast-image fork)
   - Update related dependencies if needed (e.g., react-native-bootsplash, react-native-safe-area-context)
   - Never skip steps without user confirmation

8. **Post-upgrade checklist:**
   - Provide a testing checklist including:
     - Clean builds for both platforms (`cd android && ./gradlew clean`, Xcode clean build folder)
     - New Architecture verification (if enabled)
     - Third-party integrations testing
     - Navigation and animations
     - Device-specific features (camera, location, notifications, etc.)

9. **Documentation:**
   - Summarize all changes made
   - List any manual follow-up actions required
   - Note any dependencies that still need updates
   - Provide links to relevant release notes

## Examples

**Expo app with generated or maintained native projects:**
> rn-upgrade expo <SDK target>

Reads the Expo reference, resolves compatible dependency versions, and establishes native
project ownership before choosing regeneration or manual migration. Existing `ios/` and
`android/` directories do not imply they are disposable.

**Single version upgrade:**
> /rn-upgrade 0.76

Upgrades from current version (e.g., 0.75.3) to 0.76. Fetches the diff from rn-diff-purge, checks dependency compatibility, plans changes, and executes after approval.

**Multi-version jump:**
> /rn-upgrade 0.76

When current version is 0.73 or older, the skill upgrades incrementally: 0.73 -> 0.74 -> 0.75 -> 0.76, one major version at a time, validating builds between each jump.

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `pod install` fails with version conflicts | Run `cd ios && pod repo update && pod install`. If still failing, delete `Podfile.lock` and `Pods/` then retry. |
| Gradle build fails after upgrade | Clear caches: `cd android && ./gradlew clean`. Check that `gradle-wrapper.properties` matches the version from the diff. |
| Metro bundler can't resolve modules | Clear Metro cache: `npx react-native start --reset-cache`. Also delete `node_modules` and reinstall. |
| Xcode build fails with "framework not found" | Run `cd ios && pod deintegrate && pod install`. If using use_frameworks!, check compatibility with native modules. |
| New Architecture bridge errors | Verify all native modules support the New Architecture. Check `newArchEnabled` in `gradle.properties` (Android) and Podfile flags (iOS). |
| Diff URL returns 404 | The exact patch version may not exist in rn-diff-purge. Use the nearest available version or the Upgrade Helper UI. |

## Guidelines

- Use the manual upgrade approach with diff analysis (not `react-native upgrade` CLI)
- Upgrade incrementally (one major version at a time) when jumping multiple versions
- Enable New Architecture in current version before upgrading if it's required in target
- Clear all caches after upgrade (Metro, Gradle, Pods, Derived Data)
- Test thoroughly on both iOS and Android before considering upgrade complete

## Resources

- Upgrade Helper: https://react-native-community.github.io/upgrade-helper/
- RN Diff Purge: https://github.com/react-native-community/rn-diff-purge
- React Native Docs: https://reactnative.dev/docs/upgrading
- React Native Releases: https://github.com/facebook/react-native/releases

---

Start by determining the current and target versions, then proceed with research and planning before making any changes.

