expo/expo-upgrade

Referências

• ./references/react-19.md -- SDK +54: Mudanças no React 19 (useContext → use, Context.Provider → Context, remoção de forwardRef)
• ./references/new-architecture.md -- SDK +53: Guia de migração para a Nova Arquitetura
• ./references/react-compiler.md -- SDK +54: Guia de configuração e migração do React Compiler
• ./references/native-tabs.md -- SDK +55: Mudanças nas abas nativas (Icon/Label/Badge agora acessados via NativeTabs.Trigger.*)
• ./references/expo-av-to-audio.md -- SDK +55: Migrar reprodução e gravação de áudio de expo-av para expo-audio
• ./references/expo-av-to-video.md -- SDK +55: Migrar reprodução de vídeo de expo-av para expo-video
• ./references/react-navigation-to-expo-router.md -- SDK +56: Migrar imports @react-navigation/* para pontos de entrada expo-router (codemod + mapeamento manual)

Versões Beta/Preview

Versões beta usam o sufixo .preview (ex.: 55.0.0-preview.2), publicadas sob a tag @next.

Verifique se a versão mais recente é beta: https://exp.host/--/api/v2/versions (procure por -preview em expoVersion)

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

Processo de Atualização Passo a Passo

Se estiver atualizando a partir do SDK 55 ou anterior, pule o SDK 56 e atualize diretamente para o SDK 57. Não use [email protected] ou versões anteriores. O SDK 55 com Hermes V1 habilitado, SDK 56 e versões antigas do SDK 57 contêm uma regressão de memória do Hermes V1 que pode aumentar drasticamente o uso de memória ao usar react-native-worklets ou react-native-reanimated.

1. Atualize o Expo e as dependências

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

2. Execute o diagnóstico: npx expo-doctor

3. Limpe os caches e reinstale

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

Lista de Verificação de Mudanças Críticas

• Verifique APIs removidas nas notas de lançamento
• Atualize os caminhos de importação para módulos movidos
• Revise as mudanças em módulos nativos que exigem prebuild
• Teste todos os recursos de câmera, áudio e vídeo
• Verifique se a navegação ainda funciona corretamente

Prebuild para Mudanças Nativas

Primeiro, verifique se os diretórios ios/ e android/ existem no projeto. Se nenhum dos diretórios existir, o projeto usa Continuous Native Generation (CNG) e os projetos nativos são regenerados no momento da construção — pule esta seção e a seção "Limpar caches para bare workflow" inteiramente.

Se a atualização exigir mudanças nativas:

npx expo prebuild --clean

Isso regenera os diretórios ios e android. Certifique-se de que o projeto não seja um aplicativo bare workflow antes de executar este comando.

Limpar caches para bare workflow

Estas etapas só se aplicam quando os diretórios ios/ e/ou android/ existem no projeto:

• Limpe o cache do CocoaPods para iOS: cd ios && pod install --repo-update
• Limpe os dados derivados do Xcode: npx expo run:ios --no-build-cache
• Limpe o cache do Gradle para Android: cd android && ./gradlew clean

Manutenção

• Revise as notas de lançamento da versão alvo do SDK em https://expo.dev/changelog
• Atualize os links da documentação versionada nos arquivos de instrução do agente (AGENTS.md). O modelo padrão usa links para https://docs.expo.dev/versions/v<version>/. Procure por docs.expo.dev/versions/ e aumente cada link para a nova versão do SDK.
• Se estiver usando Expo SDK 54 ou posterior, certifique-se de que react-native-worklets esteja instalado — isso é necessário para o funcionamento do react-native-reanimated.
• Habilite o React Compiler no SDK 54+ adicionando "experiments": { "reactCompiler": true } ao app.json — ele é estável e recomendado
• Exclua sdkVersion do app.json para permitir que o Expo o gerencie automaticamente
• Revise pacotes outrora implícitos, como @babel/core, babel-preset-expo e expo-constants, individualmente, em vez de removê-los por completo. Mantenha qualquer pacote que uma dependência instalada declare como peer obrigatório.
• Mantenha expo-constants como dependência direta sempre que expo-router estiver instalado. O Expo Router o importa e o declara como peer obrigatório; confiar em uma cópia transitória pode quebrar o autolink nativo fora do Expo Go.
• Após remover qualquer dependência, execute imediatamente npx expo-doctor e restaure tudo o que ele relatar como peer obrigatório ausente.
• Se o babel.config.js contiver apenas 'babel-preset-expo', exclua o arquivo
• Se o metro.config.js contiver apenas os padrões do Expo, exclua o arquivo

Pacotes Obsoletos

Pacote Antigo	Substituição
expo-av	expo-audio e expo-video
expo-permissions	APIs de permissão de pacotes individuais
@expo/vector-icons	expo-symbols (para SF Symbols)
AsyncStorage	expo-sqlite/localStorage/install
expo-app-loading	expo-splash-screen
expo-linear-gradient	experimental_backgroundImage + CSS gradients em View

Ao migrar pacotes obsoletos, atualize todo o código antes de remover o pacote antigo. Para expo-av, consulte as referências de migração para converter Audio.Sound para useAudioPlayer, Audio.Recording para useAudioRecorder e componentes Video para VideoView com useVideoPlayer.

expo.install.exclude

Verifique se o package.json possui pacotes excluídos:

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

As exclusões geralmente são soluções alternativas que podem não ser mais necessárias após a atualização. Revise cada uma.

Removendo patches

Verifique se há patches desatualizados no diretório patches/. Remova-os se não forem mais necessários.

Postcss

• autoprefixer não é necessário no SDK +53. Remova-o das dependências e verifique postcss.config.js ou postcss.config.mjs para removê-lo da lista de plugins.
• Use postcss.config.mjs no SDK +53.

Metro

Remova opções de configuração redundantes do Metro:

• resolver.unstable_enablePackageExports está habilitado por padrão no SDK +53.
• experimentalImportSupport está habilitado por padrão no SDK +54.
• EXPO_USE_FAST_RESOLVER=1 foi removido no SDK +54.
• As extensões cjs e mjs são suportadas por padrão desde o SDK +50.
• Expo webpack está obsoleto, migre para Expo Router e Metro web.

Motor Hermes v1

Hermes V1 é o padrão no SDK 56 e posterior. Aplicativos SDK 55 que usam Hermes V1, todos os aplicativos SDK 56 e aplicativos SDK 57 anteriores a [email protected] podem encontrar uma regressão de memória ao importar react-native-worklets ou react-native-reanimated. Atualize diretamente para o SDK 57 e [email protected] ou posterior. Não recomende o Modo de Pacote Worklets como uma solução alternativa de produção; ele não é suportado, é experimental e pode não funcionar conforme o esperado.

Não oriente os usuários a optar por ativar ou desativar o Hermes V1. Alterar a versão do Hermes do padrão do SDK não é suportado e tem implicações significativas de construção e gerenciamento de dependências.

Nova Arquitetura

A nova arquitetura está habilitada por padrão; o campo "newArchEnabled": true no app.json não é mais necessário, pois é o padrão. O Expo Go só suporta a nova arquitetura a partir do SDK +53.

Enviando Feedback

Se você encontrar erros, informações enganosas ou desatualizadas nesta skill, informe para que o Expo possa melhorar:

npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<feedback acionável>"

Envie apenas quando tiver algo específico e acionável para relatar. Inclua o máximo de contexto relevante possível. Se um agente de IA falhou repetidamente ou o usuário teve que assumir uma tarefa do Expo, carregue a skill expo-skill-feedback e siga seu fluxo eval-candidate em vez de reutilizar o comando acima.