| name | upgrade-react-native |
| description | Use when upgrading react-native to a newer version. Handles version bumps, native project changes (Android/iOS), dependency updates, and breaking change migration. Invoke with `/upgrade-react-native <version>`.
|
| version | 0.1.0 |
| license | MIT |
Upgrade React Native
Upgrade a React Native Community CLI project to a target version by fetching
and applying the diff from the
React Native Upgrade Helper.
[!Note]
Expo users: For Expo projects or more complex upgrade scenarios, try:
Invocation
/upgrade-react-native <targetVersion>
<targetVersion> — the React Native version to upgrade to (e.g. 0.79.0).
Step-by-step procedure
Follow every step below in order. Do not skip steps.
1. Detect the current React Native version
Read the project's root package.json and extract the react-native version
from dependencies (or devDependencies). Strip any semver range prefix
(^, ~, >=, etc.) to get the exact current version string.
If the current version cannot be determined, stop and ask the user.
2. Validate the target version
3. Fetch the upgrade diff
Fetch the unified diff between the two versions:
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<currentVersion>..<targetVersion>.diff
For example, to upgrade from 0.73.0 to 0.74.0:
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.0..0.74.0.diff
If the diff cannot be fetched (404), it may be because exact patch versions are
not available. Try the nearest minor versions (e.g. 0.73.0 instead of
0.73.2). Report what you tried and ask the user if needed.
4. Parse the diff and map file paths
The diff uses the template project name RnDiffApp. Map every path in the diff
to the actual project:
| Diff path prefix | Actual project path |
|---|
RnDiffApp/ | Project root (./) |
Additionally, replace occurrences of the template identifiers with the project's
actual names:
| Template value | Replace with |
|---|
RnDiffApp | The project's app name (from app.json → name, or the name field in package.json) |
rndiffapp | Lowercase version of the project's app name |
com.rndiffapp | The project's Android package name (from android/app/build.gradle or android/app/src/main/AndroidManifest.xml) |
5. Review the diff and plan changes
Before making any edits, review the entire diff and categorize changes:
- Direct applies — files that exist in the project and whose original
content matches the diff's
- lines. These can be applied as-is.
- Conflicts — files where the project's content has diverged from the
template (custom modifications). These need manual merging.
- New files — files in the diff that don't exist in the project yet. Create
them.
- Deleted files — files the diff removes. Delete them only if the project
hasn't added custom content to them.
Present this plan to the user before proceeding. Group changes by area:
- Root config files (
package.json, metro.config.js, .eslintrc.js, etc.)
- iOS native files (
ios/ directory)
- Android native files (
android/ directory)
- JavaScript/TypeScript source (if any template source files changed)
- Third-party native dependencies (from step 7 — include any version bumps
identified there)
6. Apply changes
Apply the changes following the plan from step 5:
- For direct applies: edit the file to match the diff's
+ lines.
- For conflicts: apply the upgrade changes while preserving the project's
customizations. Use your judgement to merge. If uncertain, show both versions
and ask the user.
- For new files: create them at the mapped path.
- For deleted files: remove them.
Important considerations:
- When updating
package.json, update the react-native version and any
related dependencies mentioned in the diff (e.g. react, @react-native/*
packages, Gradle versions, CocoaPods versions).
- Do NOT run
npm install / yarn install / pod install automatically.
Inform the user these steps are needed after the upgrade.
- Refer to the references section for version-specific guidance
on breaking changes and migration notes.
7. Update third-party native dependencies
Scan the project's dependencies and devDependencies in package.json for
third-party React Native libraries that contain native code (i.e. they have
an ios/ or android/ directory, or are known native modules). Common examples
include react-native-screens, react-native-reanimated,
react-native-gesture-handler, @react-native-async-storage/async-storage,
react-native-svg, react-native-safe-area-context, etc.
For each candidate dependency:
- Fetch the library's README from its GitHub repository or npm page.
- Look for a React Native version compatibility table or section — many
native libraries document which versions of their package support which React
Native versions (e.g. a "Compatibility" or "Version Support" table).
- If the README contains a compatibility table that maps the target React
Native version to a specific library version, include that library version
bump in the upgrade plan.
- If the README does not mention version compatibility with React Native
versions, skip the library — do not guess or assume an upgrade is needed.
Present all proposed dependency bumps alongside the diff-based changes in step 5
(grouped under a Third-party native dependencies section). For each:
- State the current version, the proposed version, and link to the compatibility
info you found.
- If multiple major versions are compatible, prefer the latest stable version
that supports the target React Native version.
Apply these version bumps to package.json as part of step 6.
8. Migrate to the Strict TypeScript API (target >= 0.87)
React Native 0.87 makes the Strict TypeScript API the default. When the upgrade crosses this boundary (current version < 0.87, target >= 0.87) and the project uses TypeScript (a tsconfig.json exists), type-checking of the project is affected and this step is required — do not silently skip it.
Ask the user which they prefer:
- Migrate now (recommended) — run the
migrate-to-strict-api skill (/migrate-to-strict-api), which handles dependency compatibility, deep import rewriting, and known breaking type changes.
- Defer with the temporary opt-out — add
"customConditions": ["react-native", "react-native-legacy-deep-imports"] to compilerOptions in tsconfig.json, keeping both entries. Tell the user this opt-out is temporary and due for removal in a future release.
For target versions below 0.87, or projects without TypeScript, skip this step and do not suggest the migration unprompted.
9. Post-upgrade checklist
After applying all changes, present the user with a checklist:
References
Consult these for version-specific migration guidance:
