Skip to main content

Version Compatibility Matrix

This document tracks version compatibility between the DigiWedge mobile stack and Gluestack UI v3 + NativeWind.

Current Stack (Expo SDK 54 Baseline)​

PackageVersionNotes
React19.2.3React 19 with concurrent features
React Native0.81.5Latest stable with Expo 54
Expo SDK54.0.9Latest stable
NX22.3.3Latest stable
antd6.1.1Native React 19 support (no patch needed)
react-native-reanimated~3.17.4Pinned for stability
react-native-safe-area-context5.4.0Meets Gluestack peer dep
react-native-gesture-handler~2.24.0SDK 54 compatible
react-native-screens~4.11.1SDK 54 compatible

Note: Expo SDK 54 is the final release that supports the legacy architecture. Track New Architecture readiness during the migration.

Gluestack UI v3 Requirements​

PackageRequiredOur VersionStatus
Expo SDK53+54.0.9Compatible
React Native~0.81+0.81.5Compatible
React18.x / 19.x19.2.3Compatible
react-native-reanimated~3.17.4~3.17.4Compatible
react-native-safe-area-context5.4.0+5.4.0Compatible

NativeWind Requirements​

PackageRequiredRecommendedNotes
nativewind4.x~4.1.0Avoid 4.2.0 (breaking issues)
tailwindcss^3.4.x^3.4.17Dev dependency
react-native-reanimated~3.17.4~3.17.4Peer dependency

Known Compatibility Issues​

Expo 54 + Gluestack (monitor)​

IssueDescriptionStatus
#3200App crashes with overlay components on Expo 54Validate overlays in dev client
#3215Fresh Expo 54 + gluestack init has dependency problemsUse pinned versions; verify wrapper build

NativeWind Issues (mitigated)​

IssueDescriptionMitigation
#1574NativeWind 4.2.0 breaks Expo appsPin to ~4.1.0
#1483NativeWind not working with ExpoUse correct babel preset

Reanimated Issues (mitigated)​

IssueDescriptionMitigation
expo#36761Babel plugin moved to react-native-workletsUpdate babel config if needed
Version mismatch3.17.5 has edge casesPinned to 3.17.4

Root Dependencies (additions)​

{
  "dependencies": {
    "nativewind": "~4.1.0",
    "@gluestack-ui/config": "^1.1.20",
    "@gluestack-ui/themed": "^1.1.73",
    "lucide-react-native": "^0.400.0"
  },
  "devDependencies": {
    "tailwindcss": "^3.4.17",
    "prettier-plugin-tailwindcss": "^0.5.11"
  }
}

Per-App Dependencies​

Each mobile app needs in its own package.json:

{
  "dependencies": {
    "@digiwedge/gluestack-ui": "workspace:*"
  }
}

Version Lock Strategy​

To ensure reproducible builds:

  1. Pin exact versions for critical packages (reanimated, safe-area-context)
  2. Use tilde (~) for minor version flexibility (nativewind, gesture-handler)
  3. Avoid caret (^) for packages with known breaking changes
  4. Lock NativeWind to 4.1.x until 4.2.x issues resolved

Upgrade Path​

SDK 54 Baseline (completed)​

  • Expo SDK 54 aligned
  • React Native 0.81.5 aligned
  • Reanimated pinned at 3.17.4

When Expo 55+ Stabilizes​

  1. Monitor gluestack-ui releases
  2. Test in isolated branch
  3. Upgrade sequence:
    • Expo SDK 54 → 55
    • React Native 0.81 → 0.82
    • Reanimated 3.17.4 → 4.x
    • Update animation components if needed

NativeWind 4.2.x​

Once fixed:

  1. Monitor nativewind releases
  2. Upgrade nativewind ~4.1.0 → ~4.2.x
  3. Test all styling

Testing Compatibility​

Before migration, validate with:

# Check peer dependencies
pnpm why react-native-reanimated
pnpm why react-native-safe-area-context

# Verify no conflicting versions
pnpm ls react-native-reanimated --depth=3
pnpm ls nativewind --depth=3

Sources​