playbooks

home / skills / callstackincubator / agent-skills / upgrading-react-native

upgrading-react-native skill

/skills/upgrading-react-native

This skill guides upgrading React Native apps with upgrade helper, dependency checks, Expo steps, and verification to reduce pitfalls.

npx playbooks add skill callstackincubator/agent-skills --skill upgrading-react-native

Review the files below or copy the command above to add this skill to your agents.

Files (9)
SKILL.md
2.5 KB
---
name: upgrading-react-native
description: React Native upgrade workflow covering updated templates, dependencies, and common pitfalls. Use when migrating a React Native app to a newer release.
license: MIT
metadata:
  author: Callstack
  tags: react-native, upgrade, upgrade-helper, npm, changelog, cocoapods, ios, android
---

# Upgrading React Native

## Overview

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

## 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][upgrading-react-native] | Router: choose the right upgrade path |
| [upgrade-helper-core.md][upgrade-helper-core] | Core Upgrade Helper workflow and reliability gates |
| [upgrading-dependencies.md][upgrading-dependencies] | Dependency compatibility checks and migration planning |
| [react.md][react] | React and React 19 upgrade alignment rules |
| [expo-sdk-upgrade.md][expo-sdk-upgrade] | Expo SDK-specific upgrade layer (conditional) |
| [upgrade-verification.md][upgrade-verification] | Manual post-upgrade verification checklist |
| [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] | Monorepo and single-repo app targeting and command scoping |

## Problem → Skill Mapping

| Problem | Start With |
|---------|------------|
| Need to upgrade React Native | [upgrade-helper-core.md][upgrade-helper-core] |
| Need dependency risk triage and migration options | [upgrading-dependencies.md][upgrading-dependencies] |
| Need React/React 19 package alignment | [react.md][react] |
| Need workflow routing first | [upgrading-react-native.md][upgrading-react-native] |
| Need Expo SDK-specific steps | [expo-sdk-upgrade.md][expo-sdk-upgrade] |
| Need manual regression validation | [upgrade-verification.md][upgrade-verification] |
| Need repo/app command scoping | [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] |

[upgrading-react-native]: references/upgrading-react-native.md
[upgrade-helper-core]: references/upgrade-helper-core.md
[upgrading-dependencies]: references/upgrading-dependencies.md
[react]: references/react.md
[expo-sdk-upgrade]: references/expo-sdk-upgrade.md
[upgrade-verification]: references/upgrade-verification.md
[monorepo-singlerepo-targeting]: references/monorepo-singlerepo-targeting.md

Overview

This skill documents a practical React Native upgrade workflow that covers template diffs, dependency updates, Expo SDK considerations, and common pitfalls. It helps teams plan and execute upgrades with verification steps to reduce regressions and restore native config changes safely.

How this skill works

The skill uses a router-based approach to choose the right upgrade path and then inspects template diffs (via an Upgrade Helper-style comparison) to reconcile native code and config changes. It includes dependency compatibility checks, alignment guidance for React and React 19, optional Expo SDK steps, and a post-upgrade verification checklist to validate the app manually.

When to use it

  • When migrating a React Native app to a newer release
  • When reconciling native template changes after an automated upgrade
  • When triaging dependency compatibility and migration risk
  • When upgrading React to match React Native expectations (e.g., React 19)
  • When preparing Expo-managed apps for SDK upgrades

Best practices

  • Run template diffs and apply native config changes incrementally, not all at once
  • Lock and test transitive dependencies; prepare migration notes for breaking changes
  • Use a staged branch and CI gating for upgrade commits to catch regressions early
  • Follow Expo-specific steps only when the app is Expo-managed; separate those changes
  • Perform manual verification (builds, smoke tests, key user flows) before release

Example use cases

  • Upgrading a bare React Native app from 0.71 to 0.72 while preserving custom native modules
  • Aligning React package versions (including React 19) to satisfy new peer dependency rules
  • Upgrading an Expo-managed project to a new Expo SDK with conditional native changes
  • Running a dependency risk triage to decide which packages need immediate upgrades or replacements
  • Validating that critical screens and native integrations still work after template merges

FAQ

Do I always need to update native templates when upgrading?

Not always, but you should inspect template diffs and apply required native config changes selectively—especially for Android and iOS manifests, gradle, and Podfile updates.

How do I handle transitive dependency breakages?

Run compatibility checks, pin versions in a temporary resolution, and either update or replace offending packages after testing in a staging branch.