Обновление Expo SDK

Переводит приложение на новый Expo SDK: expo install --fix, expo-doctor, prebuild и чистка кешей только при нативных папках, замена устаревших пакетов, заметки по SDK. Для случаев, когда нужно поднять SDK или разобрать конфликты зависимостей после него.

РазработкаПак: Скиллы Expo149 строкexpo-upgrade
Автор
Источник
expo/skills/plugins/expo/skills/expo-upgrade @ 88d9bd7
Лицензия
MIT · Copyright (c) 2025-present 650 Industries, Inc. (aka Expo)

Об этом скилле

Что делает

Скилл — порядок действий от Expo для перехода приложения на новый SDK. Основные шаги: npx expo install expo@latest, npx expo install --fix, npx expo-doctor и очистка кешей. Сначала агент смотрит, есть ли в проекте ios/ и android/. Если нет, проект живёт на Continuous Native Generation, и шаги с prebuild и нативными кешами пропускаются. Если есть, он может запустить npx expo prebuild --clean (но не в bare-приложении) и почистить кеши CocoaPods, Xcode и Gradle. Предварительные версии берутся с тега @next.

В скилле есть одно предупреждение о версиях: с SDK 55 и ниже нужно перескочить через SDK 56 сразу на SDK 57, причём не ниже [email protected], — из-за регрессии по памяти в Hermes V1 при работе с Reanimated и Worklets. Менять версию Hermes в обход проблемы агенту советовать нельзя.

Дальше — уборка: убрать sdkVersion, включить React Compiler на SDK 54+, оставить expo-constants прямой зависимостью рядом с Expo Router, после каждой удалённой зависимости снова запускать expo-doctor. Кроме того, удалить конфиги Babel и Metro, где одни значения по умолчанию, пересмотреть исключения установки и старые патчи и обновить ссылки на документацию с номером версии в AGENTS.md. Таблица сопоставляет устаревшие пакеты с заменами, например expo-av — с expo-audio и expo-video; код переводят до того, как удалить старый пакет.

Справочники привязаны к версиям SDK: react-19.md (54), new-architecture.md (53), react-compiler.md (54), native-tabs.md (55), expo-av-to-audio.md и expo-av-to-video.md (55) и react-navigation-to-expo-router.md (56) — с командой expo-codemod и ручной таблицей замены импортов.

Когда включать и когда не надо

Для перехода на новый SDK, конфликтов зависимостей после него и отказа от устаревших пакетов Expo. Обзор Expo и EAS отправляет сюда любую смену SDK, чтобы версии не поднимали вручную. Для React Native без Expo скилл не предназначен. Отдельной ветки и шага отката в нём нет, так что закоммитьте всё перед началом.

Как поставить и вызвать

Команда установки ниже скачивает всю папку. Агент сам подхватывает скилл по описанию. Вызвать вручную:

  • Claude Code: /expo-upgrade или попросить скилл по имени.
  • Codex: $expo-upgrade.
  • Cursor: наберите / в чате Agent и выберите expo-upgrade.

Пример: /expo-upgrade Переведи приложение с SDK 54 на последний стабильный SDK и замени expo-av.

Чем отличается от похожих

Вывод из эксплуатации и миграции от Эдди Османи — о том, как выводить из оборота собственные системы и API и переводить их пользователей; про Expo там ничего нет. Переход на Prisma ORM 7 — такой же пошаговый план обновления, но для другого инструмента. Больше в каталоге обновлением Expo или React Native не занимается ни один скилл, включая Лучшие практики React Native.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/expo-upgrade/SKILL.md https://anymodel.org/en/skills/expo/expo-upgrade/SKILL.md -o ~/.claude/skills/expo-upgrade/LICENSE https://anymodel.org/en/skills/expo/expo-upgrade/LICENSE -o ~/.claude/skills/expo-upgrade/agents/openai.yaml https://anymodel.org/en/skills/expo/expo-upgrade/agents/openai.yaml -o ~/.claude/skills/expo-upgrade/references/expo-av-to-audio.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-audio.md -o ~/.claude/skills/expo-upgrade/references/expo-av-to-video.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-video.md -o ~/.claude/skills/expo-upgrade/references/native-tabs.md https://anymodel.org/en/skills/expo/expo-upgrade/references/native-tabs.md -o ~/.claude/skills/expo-upgrade/references/new-architecture.md https://anymodel.org/en/skills/expo/expo-upgrade/references/new-architecture.md -o ~/.claude/skills/expo-upgrade/references/react-19.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-19.md -o ~/.claude/skills/expo-upgrade/references/react-compiler.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-compiler.md -o ~/.claude/skills/expo-upgrade/references/react-navigation-to-expo-router.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-navigation-to-expo-router.md
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/expo-upgrade/SKILL.md https://anymodel.org/en/skills/expo/expo-upgrade/SKILL.md -o ~/.agents/skills/expo-upgrade/LICENSE https://anymodel.org/en/skills/expo/expo-upgrade/LICENSE -o ~/.agents/skills/expo-upgrade/agents/openai.yaml https://anymodel.org/en/skills/expo/expo-upgrade/agents/openai.yaml -o ~/.agents/skills/expo-upgrade/references/expo-av-to-audio.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-audio.md -o ~/.agents/skills/expo-upgrade/references/expo-av-to-video.md https://anymodel.org/en/skills/expo/expo-upgrade/references/expo-av-to-video.md -o ~/.agents/skills/expo-upgrade/references/native-tabs.md https://anymodel.org/en/skills/expo/expo-upgrade/references/native-tabs.md -o ~/.agents/skills/expo-upgrade/references/new-architecture.md https://anymodel.org/en/skills/expo/expo-upgrade/references/new-architecture.md -o ~/.agents/skills/expo-upgrade/references/react-19.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-19.md -o ~/.agents/skills/expo-upgrade/references/react-compiler.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-compiler.md -o ~/.agents/skills/expo-upgrade/references/react-navigation-to-expo-router.md https://anymodel.org/en/skills/expo/expo-upgrade/references/react-navigation-to-expo-router.md
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','references/expo-av-to-audio.md','references/expo-av-to-video.md','references/native-tabs.md','references/new-architecture.md','references/react-19.md','references/react-compiler.md','references/react-navigation-to-expo-router.md') { $p = Join-Path "$HOME\.claude\skills\expo-upgrade" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/expo/expo-upgrade/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','references/expo-av-to-audio.md','references/expo-av-to-video.md','references/native-tabs.md','references/new-architecture.md','references/react-19.md','references/react-compiler.md','references/react-navigation-to-expo-router.md') { $p = Join-Path "$HOME\.agents\skills\expo-upgrade" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/expo/expo-upgrade/$f" -UseBasicParsing -OutFile $p }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/expo/expo-upgrade/SKILL.md

SKILL.md

Исходник

References

  • ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
  • ./references/new-architecture.md -- SDK +53: New Architecture migration guide
  • ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide
  • ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.*)
  • ./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio
  • ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video
  • ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate @react-navigation/* imports to expo-router entry points (codemod + manual mapping)

Beta/Preview Releases

Beta versions use .preview suffix (e.g., 55.0.0-preview.2), published under @next tag.

Check if latest is beta: https://exp.host/--/api/v2/versions (look for -preview in expoVersion)

npx expo install expo@next --fix  # install beta

Step-by-Step Upgrade Process

If upgrading from SDK 55 or earlier, skip SDK 56 and upgrade directly to SDK 57. Don't use [email protected] 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.

  1. Upgrade Expo and dependencies
npx expo install expo@latest
npx expo install --fix
  1. Run diagnostics: npx expo-doctor

  2. Clear caches and reinstall

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

Breaking Changes Checklist

  • Check for removed APIs in release notes
  • Update import paths for moved modules
  • Review native module changes requiring prebuild
  • Test all camera, audio, and video features
  • Verify navigation still works correctly

Prebuild for Native Changes

First check if ios/ and android/ directories exist in the project. If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.

If upgrading requires native changes:

npx expo prebuild --clean

This regenerates the ios and android directories. Ensure the project is not a bare workflow app before running this command.

Clear caches for bare workflow

These steps only apply when ios/ and/or android/ directories exist in the project:

  • Clear the cocoapods cache for iOS: cd ios && pod install --repo-update
  • Clear derived data for Xcode: npx expo run:ios --no-build-cache
  • Clear the Gradle cache for Android: cd android && ./gradlew clean

Housekeeping

  • Review release notes for the target SDK version at https://expo.dev/changelog
  • Update versioned docs links in agent instruction files (AGENTS.md). The default template links to https://docs.expo.dev/versions/v<version>/. Search for docs.expo.dev/versions/ and bump each link to the new SDK version.
  • If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
  • Enable React Compiler in SDK 54+ by adding "experiments": { "reactCompiler": true } to app.json — it's stable and recommended
  • Delete sdkVersion from app.json to let Expo manage it automatically
  • 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.
  • 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.
  • After removing any dependency, immediately run npx expo-doctor and restore anything it reports as a missing required peer.
  • If the babel.config.js only contains 'babel-preset-expo', delete the file
  • If the metro.config.js only contains expo defaults, delete the file

Deprecated Packages

Old Package Replacement
expo-av expo-audio and expo-video
expo-permissions Individual package permission APIs
@expo/vector-icons expo-symbols (for SF Symbols)
AsyncStorage expo-sqlite/localStorage/install
expo-app-loading expo-splash-screen
expo-linear-gradient experimental_backgroundImage + CSS gradients in View

When 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.

expo.install.exclude

Check if package.json has excluded packages:

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

Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.

Removing patches

Check if there are any outdated patches in the patches/ directory. Remove them if they are no longer needed.

Postcss

  • 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.
  • Use postcss.config.mjs in SDK +53.

Metro

Remove redundant metro config options:

  • resolver.unstable_enablePackageExports is enabled by default in SDK +53.
  • experimentalImportSupport is enabled by default in SDK +54.
  • EXPO_USE_FAST_RESOLVER=1 is removed in SDK +54.
  • cjs and mjs extensions are supported by default in SDK +50.
  • Expo webpack is deprecated, migrate to Expo Router and Metro web.

Hermes engine v1

Hermes V1 is the default on SDK 56 and later. SDK 55 apps using Hermes V1, all SDK 56 apps, and SDK 57 apps before [email protected] may encounter a memory regression when importing react-native-worklets or react-native-reanimated. Upgrade directly to SDK 57 and [email protected] or later. Do not recommend Worklets Bundle Mode as a production workaround; it is unsupported and experimental and may not work as expected.

Do 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.

New Architecture

The 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.

Submitting Feedback

You can voluntarily report errors, misleading or outdated information in this skill, so Expo can improve it:

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-upgrade" --message "<actionable feedback>"

Use --category agent-cli for a problem with the agent CLI, and --category evals when an agent repeatedly fails at an Expo task. Run feedback --help for subjects and the data that the command sends. Each report goes to Expo with project and environment details. Show the user the message, and send it only if the user agrees. If you cannot ask the user, do not send it. Do not include secrets or personal data.

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Скиллы Expo

Обзор Expo и EAS

Направляет задачи по Expo и EAS в нужный скилл Expo и задаёт общие правила: агентский CLI, определение SDK, документация своей версии, установка пакетов под SDK, проверка входа в EAS. Для случаев, когда в задаче есть Expo или EAS или проект зависит от expo.

Навигация в Expo Router

Раскладывает маршруты по соглашениям Expo Router и подключает нативную навигацию: Stack, NativeTabs, превью ссылок, контекстные меню, модальные окна, шторки, поиск в шапке. Для случаев, когда нужно выстроить навигацию в приложении на Expo Router.

Нативные экраны в Expo

Оформляет экраны Expo по правилам iOS и Android: выбор библиотек, безопасные зоны, системные цвета через Color, SF Symbols, контролы, медиа, хранилище и эффекты, сначала Expo Go. Для случаев, когда вы делаете или переделываете экраны в приложении на Expo.

Сборки EAS для App Store и Google Play

Собирает и отправляет приложения для iOS и Android через EAS в TestFlight, App Store и Google Play: только проверенные сборки по ID, учётные данные остаются у владельца. Для случаев, когда нужно настроить сборки, подпись, версии, отправку или метаданные.

EAS Update: обновления по воздуху

Настраивает и публикует обновления по воздуху через EAS Update, сверяет канал, ветку и runtime version и разбирает, почему сборка показывает старый код. Для случаев, когда исправление JS или ассетов нужно доставить без новой сборки.