expo/expo-upgrade

Referenzen

• ./references/react-19.md -- SDK +54: React 19 Änderungen (useContext → use, Context.Provider → Context, forwardRef entfernt)
• ./references/new-architecture.md -- SDK +53: Migrationsleitfaden für die neue Architektur
• ./references/react-compiler.md -- SDK +54: React Compiler Einrichtung und Migrationsleitfaden
• ./references/native-tabs.md -- SDK +55: Änderungen an Native Tabs (Icon/Label/Badge jetzt über NativeTabs.Trigger.* aufrufbar)
• ./references/expo-av-to-audio.md -- SDK +55: Migration der Audiowiedergabe und -aufnahme von expo-av zu expo-audio
• ./references/expo-av-to-video.md -- SDK +55: Migration der Videowiedergabe von expo-av zu expo-video
• ./references/react-navigation-to-expo-router.md -- SDK +56: Migration von @react-navigation/*-Imports zu expo-router-Einstiegspunkten (Codemod + manuelle Zuordnung)

Beta/Preview-Releases

Beta-Versionen verwenden das Suffix .preview (z. B. 55.0.0-preview.2) und werden unter dem Tag @next veröffentlicht.

Prüfen, ob die neueste Version eine Beta ist: https://exp.host/--/api/v2/versions (Suche nach -preview in expoVersion)

npx expo install expo@next --fix  # Beta installieren

Schritt-für-Schritt-Upgrade-Prozess

Wenn du von SDK 55 oder früher aktualisierst, überspringe SDK 56 und aktualisiere direkt auf SDK 57. Verwende nicht [email protected] oder niedriger. SDK 55 mit aktiviertem Hermes V1, SDK 56 und ältere SDK 57-Releases enthalten einen Hermes V1-Speicherregressionsfehler, der die Speichernutzung bei Verwendung von react-native-worklets oder react-native-reanimated drastisch erhöhen kann.

1. Expo und Abhängigkeiten aktualisieren

npx expo install expo@latest
npx expo install --fix

2. Diagnose ausführen: npx expo-doctor

3. Caches leeren und neu installieren

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Checkliste für Breaking Changes

• Entfernte APIs in den Release-Notes überprüfen
• Importpfade für verschobene Module aktualisieren
• Native Moduländerungen überprüfen, die Prebuild erfordern
• Alle Kamera-, Audio- und Videofunktionen testen
• Navigation funktioniert noch korrekt bestätigen

Prebuild für native Änderungen

Überprüfe zunächst, ob die Verzeichnisse ios/ und android/ im Projekt vorhanden sind. Wenn keines der Verzeichnisse existiert, verwendet das Projekt Continuous Native Generation (CNG) und native Projekte werden zur Build-Zeit neu generiert – überspringe diesen Abschnitt und „Caches für Bare Workflow leeren" vollständig.

Wenn das Upgrade native Änderungen erfordert:

npx expo prebuild --clean

Dies generiert die Verzeichnisse ios und android neu. Stelle sicher, dass das Projekt keine Bare-Workflow-App ist, bevor du diesen Befehl ausführst.

Caches für Bare Workflow leeren

Diese Schritte gelten nur, wenn ios/ und/oder android/ Verzeichnisse im Projekt vorhanden sind:

• Den CocoaPods-Cache für iOS leeren: cd ios && pod install --repo-update
• Derivate Daten für Xcode leeren: npx expo run:ios --no-build-cache
• Den Gradle-Cache für Android leeren: cd android && ./gradlew clean

Haushaltsführung

• Release-Notes für die Ziel-SDK-Version unter https://expo.dev/changelog überprüfen
• Versionsabhängige Dokumentationslinks in Agenten-Anweisungsdateien (AGENTS.md) aktualisieren. Die Standardvorlage verweist auf https://docs.expo.dev/versions/v<version>/. Suche nach docs.expo.dev/versions/ und erhöhe jeden Link auf die neue SDK-Version.
• Wenn du SDK 54 oder höher verwendest, stelle sicher, dass react-native-worklets installiert ist – dies wird für react-native-reanimated benötigt.
• React Compiler in SDK 54+ aktivieren, indem "experiments": { "reactCompiler": true } zu app.json hinzugefügt wird – es ist stabil und wird empfohlen
• sdkVersion aus app.json löschen, damit Expo es automatisch verwaltet
• Früher implizite Pakete wie @babel/core, babel-preset-expo und expo-constants einzeln überprüfen, anstatt sie vollständig zu entfernen. Behalte jedes Paket, das eine installierte Abhängigkeit als erforderliches Peer deklariert.
• Behalte expo-constants als direkte Abhängigkeit, wenn expo-router installiert ist. Expo Router importiert es und deklariert es als erforderliches Peer; sich auf eine transitive Kopie zu verlassen, kann das native Autolinking außerhalb von Expo Go unterbrechen.
• Nach dem Entfernen einer Abhängigkeit sofort npx expo-doctor ausführen und alles wiederherstellen, was als fehlendes erforderliches Peer gemeldet wird.
• Wenn die babel.config.js nur 'babel-preset-expo' enthält, die Datei löschen
• Wenn die metro.config.js nur Expo-Standardeinstellungen enthält, die Datei löschen

Veraltete Pakete

Altes Paket	Ersatz
expo-av	expo-audio und expo-video
expo-permissions	Individuelle Paketberechtigungs-APIs
@expo/vector-icons	expo-symbols (für SF-Symbole)
AsyncStorage	expo-sqlite/localStorage/install
expo-app-loading	expo-splash-screen
expo-linear-gradient	experimental_backgroundImage + CSS-Verläufe in View

Wenn du veraltete Pakete migrierst, aktualisiere die gesamte Code-Nutzung, bevor du das alte Paket entfernst. Für expo-av konsultiere die Migrationsreferenzen, um Audio.Sound in useAudioPlayer, Audio.Recording in useAudioRecorder und Video-Komponenten in VideoView mit useVideoPlayer zu konvertieren.

expo.install.exclude

Überprüfen, ob package.json ausgeschlossene Pakete enthält:

{
  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
}

Ausschlüsse sind oft Workarounds, die nach einem Upgrade möglicherweise nicht mehr benötigt werden. Jede Ausschluss prüfen.

Patches entfernen

Überprüfen, ob es veraltete Patches im Verzeichnis patches/ gibt. Entferne sie, wenn sie nicht mehr benötigt werden.

Postcss

• autoprefixer wird in SDK +53 nicht benötigt. Entferne es aus den Abhängigkeiten und überprüfe postcss.config.js oder postcss.config.mjs, um es aus der Plugin-Liste zu entfernen.
• Verwende postcss.config.mjs in SDK +53.

Metro

Redundante Metro-Konfigurationsoptionen entfernen:

• resolver.unstable_enablePackageExports ist in SDK +53 standardmäßig aktiviert.
• experimentalImportSupport ist in SDK +54 standardmäßig aktiviert.
• EXPO_USE_FAST_RESOLVER=1 wurde in SDK +54 entfernt.
• cjs- und mjs-Erweiterungen werden ab SDK +50 standardmäßig unterstützt.
• Expo Webpack ist veraltet, migriere zu Expo Router und Metro Web.

Hermes Engine v1

Hermes V1 ist die Standardversion ab SDK 56. SDK 55-Apps, die Hermes V1 verwenden, alle SDK 56-Apps und SDK 57-Apps vor [email protected] können eine Speicherregression erleiden, wenn sie react-native-worklets oder react-native-reanimated importieren. Aktualisiere direkt auf SDK 57 und [email protected] oder höher. Empfehle den Worklets Bundle-Modus nicht als Produktions-Workaround; er wird nicht unterstützt und ist experimentell und funktioniert möglicherweise nicht wie erwartet.

Weise Benutzer nicht an, sich für oder gegen Hermes V1 zu entscheiden. Das Ändern der Hermes-Version von der SDK-Standardeinstellung wird nicht unterstützt und hat erhebliche Auswirkungen auf den Build und das Abhängigkeitsmanagement.

Neue Architektur

Die neue Architektur ist standardmäßig aktiviert, das Feld "newArchEnabled": true in app.json ist nicht mehr erforderlich, da es der Standard ist. Expo Go unterstützt nur die neue Architektur ab SDK +53.

Feedback senden

Wenn du Fehler, irreführende oder veraltete Informationen in diesem Skill findest, melde sie, damit Expo verbessert werden kann:

npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<aktionierbares Feedback>"

Sende nur Feedback, wenn du etwas Konkretes und Umsetzbares zu berichten hast. Füge so viele relevante Zusammenhänge wie möglich hinzu. Wenn ein KI-Agent wiederholt fehlgeschlagen ist oder der Benutzer eine Expo-Aufgabe übernehmen musste, lade den Skill expo-skill-feedback und folge stattdessen dessen eval-candidate-Ablauf.