React Native Version Checker & Package Compatibility Guide

Understand React Native versioning, check package compatibility, and navigate upgrades safely. Includes commands to verify your environment, detect conflicts, and follow the correct upgrade path.

Check Your Current React Native Version

React Native version checks operate at three levels: the CLI, the installed package, and the native layer. All three should agree.

# Check React Native CLI version
npx react-native --version

# Check installed package version in node_modules
node -e "console.log(require('react-native/package.json').version)"

# Check your project's declared version
cat package.json | grep '"react-native"'

# Run the full environment health check
npx react-native doctor

The react-native doctor command is the most useful diagnostic — it checks your Xcode version, Android SDK, JDK, CocoaPods, and environment variables in one pass, flagging anything that could cause build failures.

Checking Package Compatibility

Before installing a new package, verify it supports your React Native version. Most packages document compatibility in their README under "Requirements" or "Installation".

# Check a package's peer dependencies before installing
npm info react-native-reanimated peerDependencies

# Example output:
# { 'react-native': '>=0.68.0', react: '>=17.0.0' }

# List all peer dependency warnings in your project
npm ls --depth=0 2>&1 | grep WARN

# For Expo projects, use expo install instead of npm install
# It automatically selects the compatible version
npx expo install react-native-reanimated

Expo's expo install command resolves compatibility automatically — it selects the package version that matches your Expo SDK's bundled React Native version. For bare React Native projects, you must check compatibility manually or use npx expo install if you're on an Expo-managed setup.

Common Version-Related Issues

The most common problems that arise from version mismatches:

Upgrade Path Guide

Upgrading React Native requires updating both JavaScript dependencies and the native template files (android/, ios/). The React Native Upgrade Helper generates a diff between versions:

# Step 1: Check the Upgrade Helper diff
# Visit: https://react-native-community.github.io/upgrade-helper/
# Enter your current and target versions

# Step 2: Update package.json
npm install [email protected]

# Step 3: Update React peer dependency
npm install [email protected]

# Step 4: Apply native file changes from Upgrade Helper diff
# Manually edit android/ and ios/ files as shown in the diff

# Step 5: Update iOS dependencies
cd ios && pod install && cd ..

# Step 6: Clean and rebuild
npx react-native clean
npx react-native run-ios
npx react-native run-android

New Architecture Compatibility Check

React Native's New Architecture (JSI + Fabric + TurboModules) is the default in 0.73+. Not all packages support it yet. Check compatibility before enabling:

# Check if a package supports New Architecture
# Look for these indicators in the package repo:

# 1. turbo-module-spec in package.json
# 2. 'fabric' or 'turbomodule' in the package keywords
# 3. A "New Architecture" section in the README
# 4. The reactNativeMetadata field in package.json:
npm info react-native-reanimated | grep -i "fabric\|turbo\|new arch"

# For Expo projects, check compatibility with expo-doctor
npx expo-doctor

# Temporarily disable New Architecture if a package blocks you
# In android/gradle.properties:
# newArchEnabled=false