Index of every page on this site: llms.txt
All skills
nielsmadan avatar

/rn-upgrade

@9fbe49f
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/nielsmadan/agentic-coding/rn-upgrade

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈51 tokens for metadata: the name and description. ≈2k when used: this file. ≈1.3k more on demand in 1 file.

Description uses 2.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈206 characters, or 2.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 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:

  2. Research and validate:

  3. Fetch the upgrade diff:

  4. Check dependency compatibility:

  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


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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning7mo4 checks · Risk SAFE
  • Gen Agent Trust Hub7mo

    The skill provides a legitimate workflow for upgrading React Native applications. It uses well-known community resources and official documentation to guide the upgrade process. Security is maintained through a mandatory planning phase that requires user approval before any changes or commands are executed.

  • Socket7mo

    No alerts

  • Snyk7mo

    Risk: MEDIUM · 2 issues

  • Runlayer8mo

    1/1 file flagged

Signed by skilld at 9fbe49f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated last week
argument-hint
<RN version or Expo SDK target>

README badge

README badge for nielsmadan/agentic-coding/rn-upgrade