Skip to content

Doko-Demo-Doa/react-native-pdf-editor / .agents/skills/upgrading-react-native

upgrading-react-native

Verified

Upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, updating package.json dependencies, migrating native iOS and Android configuration, resolving CocoaPods and Gradle changes, and handling breaking API updates. Use when upgrading React Native, bumping RN version, updating from RN 0.x to 0.y, or migrating Expo SDK alongside a React Native upgrade.

references/upgrade-helper-core.md

View on GitHub
---
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](upgrading-react-native.md) under `Prerequisites (All Upgrade Paths)`.

## Quick Commands

```bash
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](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](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](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](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](upgrading-react-native.md) - Routing and mode selection
- [upgrading-dependencies.md](upgrading-dependencies.md) - Dependency compatibility and migration plan
- [expo-sdk-upgrade.md](expo-sdk-upgrade.md) - Expo-only layer on top of core workflow
- [react.md](react.md) - React and React 19 alignment
- [upgrade-verification.md](upgrade-verification.md) - Post-upgrade validation, including agent-device-assisted checks
- [monorepo-singlerepo-targeting.md](monorepo-singlerepo-targeting.md) - Repo/app selection and command scoping
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall