ContextQMD
Back to Nx

Expo SDK 56 Migration Instructions for LLM

packages/expo/src/migrations/update-23-1-0/ai-instructions-for-expo-56.md

23.1.05.3 KB
Original Source

Expo SDK 56 Migration Instructions for LLM

Overview

These instructions guide you through migrating an Nx workspace containing Expo projects to Expo SDK 56. The most common starting points are Expo SDK 54 and SDK 55. Work systematically through each breaking change category and validate after every step.

Pre-Migration Checklist

  1. Identify all Expo projects:

    bash
    nx show projects --with-target start

  2. Locate all Expo configuration files:

    • Search for app.json or app.config.{js,ts}
    • Search for metro.config.{js,ts}
    • Search for babel.config.{js,ts}
    • Check project.json files for Expo-related configuration

  3. Record the current SDK for each project (read expo in each app's package.json).

  4. Check for Detox E2E testing projects:

    • Search for detox in package.json dependencies
    • Look for detox.config.js or .detoxrc.js files

Target Versions (Expo SDK 56)

When updating an app's package.json, align to these versions:

  • expo: ~56.0.0
  • @expo/cli: ~56.1.14
  • react: ^19.2.0
  • react-dom: ^19.2.0
  • @types/react: ^19.2.0
  • react-native: 0.85.3
  • react-native-web: ~0.21.0
  • @expo/metro: ~56.0.0
  • @expo/metro-runtime: ~56.0.14
  • babel-preset-expo: ~56.0.14
  • jest-expo: ~56.0.4
  • expo-splash-screen: ~56.0.10
  • expo-status-bar: ~56.0.4
  • expo-system-ui: ~56.0.5

Prefer npx expo install --fix inside each project to let Expo resolve the exact compatible native module versions for SDK 56, then reconcile the workspace root package.json.

Migration Steps by Category

1. React 19.2 and React Native 0.85

Expo SDK 56 uses React 19.2 and React Native 0.85.

Action Items:

  • Update @types/react to ^19.2.0
  • Verify third-party libraries are compatible with React 19.2 / RN 0.85
  • Re-run typecheck: nx run-many -t typecheck

2. Metro is now provided through @expo/metro

Starting with SDK 55, Expo bundles Metro through the @expo/metro package family rather than depending on the standalone metro, metro-config, and metro-resolver packages directly.

Search Pattern: metro.config.{js,ts}, direct imports of metro-config / metro-resolver

Action Items:

  • Add @expo/metro (~56.0.0) as a direct dependency — the generated metro.config.js and withNxMetro require @expo/metro/metro-config, which package managers like pnpm won't resolve from a transitive dependency
  • Source the Metro config from the Expo-provided instance: getDefaultConfig from expo/metro-config and mergeConfig from @expo/metro/metro-config
  • Remove direct dependencies on standalone metro / metro-config / metro-resolver, and do not install @expo/metro-config directly (expo-doctor flags it) — @expo/metro replaces them
  • If you wrap config with withNxMetro from @nx/expo, leave it in place — it continues to merge Nx workspace resolution
  • Clear the Metro cache after upgrading: npx expo start --clear

3. Babel preset

SDK 56 updates babel-preset-expo to ~56.0.14.

Action Items:

  • Update babel-preset-expo to ~56.0.14
  • Remove deprecated Babel plugins
  • Clear Metro cache after Babel changes: npx expo start --clear

4. Jest configuration

Expo v54+ (including SDK 56) relies on the winter runtime. New projects generated by @nx/expo no longer use the custom jest.resolver.js; instead src/test-setup.ts mocks expo/src/winter/ImportMetaRegistry and polyfills structuredClone.

Action Items:

  • If migrating from SDK 53, remove jest.resolver.js and the resolver: line from jest.config.ts
  • Ensure src/test-setup.ts mocks ImportMetaRegistry and polyfills structuredClone
  • Update jest-expo to ~56.0.4

5. Detox E2E Testing

Verify Detox supports Expo SDK 56 before migrating. If your workspace includes Detox projects and Detox has not yet published SDK 56 support, ask the user:

"Your workspace contains Detox E2E tests. Confirm Detox supports Expo SDK 56 before proceeding, or these tests may not run after migrating."

Consider Maestro as an alternative if Detox support lags.

Post-Migration Validation

1. Clear All Caches

bash
npx expo start --clear
rm -rf node_modules/.cache/metro-*
nx reset

2. Run Tests Per Project

bash
nx run-many -t test -p PROJECT_NAME

3. Run All Affected Tests

bash
nx affected -t test,lint,typecheck

4. Test on Device/Simulator

bash
nx run PROJECT_NAME:run-ios
nx run PROJECT_NAME:run-android

5. Review Migration Checklist

  • All Expo apps pinned to SDK 56 versions
  • React 19.2 / React Native 0.85 compatibility verified
  • Metro provided via @expo/metro; caches cleared
  • Babel and Jest configurations updated
  • All tests pass
  • App runs on iOS simulator/device
  • App runs on Android emulator/device

Notes for LLM Execution

  1. Work systematically: Complete one category before moving to the next.
  2. Test after each change: Don't batch all changes without validation.
  3. Prefer npx expo install --fix per project to resolve native module versions.
  4. Keep the user informed and create meaningful, grouped commits.
  5. Use the TodoWrite tool to track migration progress.
  6. Test on both platforms — Expo changes often affect iOS and Android differently.