AutoGineer
Generated banner for Upgrading React Native
Generated logo for Upgrading React Native

Upgrading React Native

CallstackOfficialPublished by Callstack

  • Skill
  • Workflow
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

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.
— the description by Callstack

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured, multi-step procedure for upgrading React Native applications to newer versions. It covers the entire lifecycle of an upgrade, from selecting the correct path and fetching template diffs to managing dependency compatibility, aligning React versions, and performing post-upgrade verification. It includes specific guidance for handling native iOS and Android configuration changes, resolving CocoaPods and Gradle issues, and integrating Expo SDK upgrades where applicable.

What it does

  • Guides users through the complete React Native upgrade sequence.
  • Facilitates fetching and applying canonical template diffs.
  • Assists in assessing and updating third-party dependencies.
  • Provides instructions for Expo SDK-specific upgrade layers.
  • Includes steps for post-upgrade verification and build validation.
  • Defines scoping rules for monorepo and single-repo project structures.

When to use it

  • When moving a React Native application to a newer version.
  • When reconciling native configuration changes after a version bump.
  • When migrating an Expo SDK version alongside a React Native upgrade.
  • When validating release notes for breaking changes.
  • When managing dependency compatibility during an upgrade.

Advantages

  • Provides a standardized, repeatable process for complex upgrades.
  • Reduces manual error by offering clear routing and verification steps.
  • Supports both standard React Native and Expo-managed workflows.
  • Ensures native platform configurations are correctly reconciled.
  • Includes specific guidance for monorepo environments.

Usage examples

“How do I start upgrading my React Native app from version 0.76.9 to 0.78.2?”
The agent will guide you to fetch the template diff using the Upgrade Helper, update your package.json, reconcile native changes, and run build verification.
“I need to upgrade my Expo-based React Native app, what should I do?”
The agent will provide the Expo SDK upgrade layer workflow, including running expo-doctor and aligning expo-modules.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/callstackincubator/upgrading-react-native/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip upgrading-react-native.zip -d .agents/skills

Documentation by Callstack

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

FileDescription
upgrading-react-native.mdRouter: choose the right upgrade path
upgrade-helper-core.mdCore Upgrade Helper workflow and reliability gates
upgrading-dependencies.mdDependency compatibility checks and migration planning
react.mdReact and React 19 upgrade alignment rules
expo-sdk-upgrade.mdExpo SDK-specific upgrade layer (conditional)
upgrade-verification.mdPost-upgrade verification checklist, including agent-device-assisted checks
monorepo-singlerepo-targeting.mdMonorepo and single-repo app targeting and command scoping

Problem → Skill Mapping

ProblemStart With
Need to upgrade React Nativeupgrade-helper-core.md
Need dependency risk triage and migration optionsupgrading-dependencies.md
Need React/React 19 package alignmentreact.md
Need workflow routing firstupgrading-react-native.md
Need Expo SDK-specific stepsexpo-sdk-upgrade.md
Need manual or agent-assisted regression validationupgrade-verification.md
Need repo/app command scopingmonorepo-singlerepo-targeting.md

Files

references/expo-sdk-upgrade.md

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:

  • 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.

  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

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Callstack
Publisher
Callstack (Official)
Source
callstackincubator/agent-skills · skills/upgrading-react-native · commit 59e9d17
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Callstack.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download upgrading-react-native.zip