Update to Expo2

{
  "description": "Upgrade an Expo app's SDK and resolve compatibility issues. Use for SDK migrations, expo-doctor diagnostics, dependency version conflicts, deprecated package replacements, or native changes required by an upgrade.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 373
    },
    {
      "relative_path": "references/expo-av-to-audio.md",
      "size_in_bytes": 3683
    },
    {
      "relative_path": "references/expo-av-to-video.md",
      "size_in_bytes": 4262
    },
    {
      "relative_path": "references/native-tabs.md",
      "size_in_bytes": 3520
    },
    {
      "relative_path": "references/new-architecture.md",
      "size_in_bytes": 2331
    },
    {
      "relative_path": "references/react-19.md",
      "size_in_bytes": 1875
    },
    {
      "relative_path": "references/react-compiler.md",
      "size_in_bytes": 1645
    },
    {
      "relative_path": "references/react-navigation-to-expo-router.md",
      "size_in_bytes": 4482
    }
  ],
  "name": "expo-upgrade",
  "skill_md_contents": "---\nname: expo-upgrade\ndescription: Upgrade an Expo app's SDK and resolve compatibility issues. Use for SDK migrations, expo-doctor diagnostics, dependency version conflicts, deprecated package replacements, or native changes required by an upgrade.\nlicense: MIT\n---\n\n## References\n\n- ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)\n- ./references/new-architecture.md -- SDK +53: New Architecture migration guide\n- ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide\n- ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.\\*)\n- ./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio\n- ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video\n- ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate `@react-navigation/*` imports to `expo-router` entry points (codemod + manual mapping)\n\n## Beta/Preview Releases\n\nBeta versions use `.preview` suffix (e.g., `55.0.0-preview.2`), published under `@next` tag.\n\nCheck if latest is beta: https://exp.host/--/api/v2/versions (look for `-preview` in `expoVersion`)\n\nUse a preview only when the user requests one. Resolve the requested SDK's exact release from official Expo/package metadata, then install that version; a mutable `next` tag can move to another preview while the migration is in progress.\n\n## Step-by-Step Upgrade Process\n\n> For a compatible project upgrading from SDK 55 or earlier to the current stable SDK, prefer SDK 57 over SDK 56. Don't use `expo@57.0.8` or below. SDK 55 with Hermes V1 enabled, SDK 56, and older SDK 57 releases contain a Hermes V1 memory regression that can drastically increase memory usage when using `react-native-worklets` or `react-native-reanimated`. If the requested target differs or the host cannot support SDK 57, explain this tradeoff before changing the target.\n\n1. Inspect the current SDK, package manager, lockfile, and native project ownership. Resolve the requested target to an exact Expo release; do not silently select a newer major or a preview. Preserve a commit or backup of existing changes before migration, and use the project's installed CLI and package manager.\n\n```bash\nnpx expo install 'expo@<verified-target-version>'\nnpx expo install --fix\n```\n\n2. Run diagnostics: `npx expo-doctor`\n\n3. Clear the project's bundler cache if diagnostics show stale artifacts:\n\n```bash\nnpx expo export -p ios --clear\n```\n\nReinstall dependencies with the existing lockfile only when needed. Before deleting generated directories, verify the project root and exact paths, check for symlinks or custom contents, and preserve anything needed. Do not use a global Watchman reset: if a watch is stale, remove only this project's watch with `watchman watch-del <verified-project-root>`. Do not delete unrelated caches or lockfiles.\n\n## Breaking Changes Checklist\n\n- Check for removed APIs in release notes\n- Update import paths for moved modules\n- Review native module changes requiring prebuild\n- Test all camera, audio, and video features\n- Verify navigation still works correctly\n\n## Prebuild for Native Changes\n\n**Determine whether native projects are generated or manually maintained**, rather than inferring ownership from directory presence alone. If neither `ios/` nor `android/` exists, CNG can generate them later; there is nothing to clean now. In a bare or brownfield app, apply the SDK's native changes selectively and preserve hand-maintained code.\n\nUse clean prebuild only for verified disposable CNG output. It deletes and regenerates native directories: inspect their tracked and untracked changes and preserve a recoverable commit or backup first. If ownership or recoverability is unclear, stop before cleaning and resolve it with the user. For an authorized CNG regeneration:\n\n```bash\nnpx expo prebuild --clean\n```\n\nInspect the resulting diff and verify builds. A clean prebuild is not a general recovery step for native hosts.\n\n## Clear caches for bare workflow\n\nUse these targeted recovery steps only for a diagnosed native build issue, in the verified project directory. Preserve hand-maintained native files:\n\n- Refresh CocoaPods specs and reinstall when required by the dependency change: `cd ios && pod install --repo-update`\n- Clear derived data for Xcode: `npx expo run:ios --no-build-cache`\n- Clear the Gradle cache for Android: `cd android && ./gradlew clean`\n\n## Housekeeping\n\n- Review release notes for the target SDK version at https://expo.dev/changelog\n- Update only the relevant versioned Expo documentation links in agent instruction files (`AGENTS.md`) to the selected SDK. Preserve the file's other instructions.\n- If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.\n- Enable React Compiler in SDK 54+ by adding `\"experiments\": { \"reactCompiler\": true }` to app.json — it's stable and recommended\n- Delete sdkVersion from `app.json` to let Expo manage it automatically\n- Review formerly implicit packages such as `@babel/core`, `babel-preset-expo`, and `expo-constants` individually instead of removing them wholesale. Keep any package that an installed dependency declares as a required peer.\n- Keep `expo-constants` as a direct dependency whenever `expo-router` is installed. Expo Router imports it and declares it as a required peer; relying on a transitive copy can break native autolinking outside Expo Go.\n- After removing any dependency, immediately run `npx expo-doctor` and restore anything it reports as a missing required peer.\n- Keep Babel and Metro configuration unless the selected SDK makes a file redundant and no project tooling references it. Preserve custom transforms, resolvers, and security checks. If removing a redundant file, review its diff and verify exports and native builds afterward.\n\n## Deprecated Packages\n\n| Old Package          | Replacement                                          |\n| -------------------- | ---------------------------------------------------- |\n| `expo-av`            | `expo-audio` and `expo-video`                        |\n| `expo-permissions`   | Individual package permission APIs                   |\n| `@expo/vector-icons` | `expo-symbols` (for SF Symbols)                      |\n| `AsyncStorage`       | `expo-sqlite/localStorage/install`                   |\n| `expo-app-loading`   | `expo-splash-screen`                                 |\n| expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |\n\nWhen migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.\n\n## expo.install.exclude\n\nCheck if package.json has excluded packages:\n\n```json\n{\n  \"expo\": { \"install\": { \"exclude\": [\"react-native-reanimated\"] } }\n}\n```\n\nExclusions are often workarounds that may no longer be needed after upgrading. Review each one.\n\n## Removing patches\n\nReview each patch against the upgraded dependency. Remove it only when the upstream release includes its fix and the affected behavior is verified. A patch failing to apply is not evidence that its fix, including a security fix, is unnecessary; preserve or port required patches.\n\n## Postcss\n\n- `autoprefixer` isn't needed in SDK +53. Remove it from dependencies and check `postcss.config.js` or `postcss.config.mjs` to remove it from the plugins list.\n- Use `postcss.config.mjs` in SDK +53.\n\n## Metro\n\nRemove redundant metro config options:\n\n- resolver.unstable_enablePackageExports is enabled by default in SDK +53.\n- `experimentalImportSupport` is enabled by default in SDK +54.\n- `EXPO_USE_FAST_RESOLVER=1` is removed in SDK +54.\n- cjs and mjs extensions are supported by default in SDK +50.\n- Expo webpack is deprecated, migrate to [Expo Router and Metro web](https://docs.expo.dev/router/migrate/from-expo-webpack/).\n\n## Hermes engine v1\n\nHermes V1 is the default on SDK 56 and later. SDK 55 apps using Hermes V1, all SDK 56 apps, and SDK 57 apps before `expo@57.0.9` may encounter a memory regression when importing `react-native-worklets` or `react-native-reanimated`. For a compatible project targeting SDK 57, use `expo@57.0.9` or later. If a different target is requested or the host cannot support SDK 57, explain the regression and compatibility tradeoff before changing the target. Do not recommend Worklets Bundle Mode as a production workaround; it is unsupported and experimental and may not work as expected.\n\nDo not guide users to opt in to or out of Hermes V1. Changing the Hermes version from the SDK default is unsupported and has significant build and dependency-management caveats.\n\n## New Architecture\n\nThe new architecture is enabled by default, the app.json field `\"newArchEnabled\": true` is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.\n\n## Submitting Feedback\nWhen the user requests feedback submission, use:\n```bash\nnpx --yes @expo/agent-cli@1.0.23 feedback --category skills --subject \"expo-upgrade\" \"<actionable feedback>\"\n```\nInclude only relevant technical details; keep credentials, private data, and conversation contents out of feedback.\n"
}