upgrading-expo

Quando Usar

Use esta habilidade quando precisar de diretrizes para atualizar versões do Expo SDK e corrigir problemas de dependência.

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 da Nova Arquitetura
• ./references/react-compiler.md -- SDK +54: Configuração e guia de 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 importações @react-navigation/* para pontos de entrada expo-router (codemod + mapeamento manual)

Lançamentos Beta/Preview

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

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

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

Processo de Atualização Passo a Passo

1. Atualize o Expo e as dependências

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

2. Execute os diagnósticos: npx expo-doctor

3. Limpe caches e reinstale

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

Checklist de Mudanças Quebrando

• Verifique APIs removidas nas notas de lançamento
• Atualize caminhos de importação para módulos movidos
• Revise 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 Geração Nativa Contínua (CNG) e os projetos nativos são regenerados no momento da compilação — pule esta seção e "Limpar caches para fluxo nu" completamente.

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 é um aplicativo de fluxo nu antes de executar este comando.

Limpar caches para fluxo nu

Estas etapas se aplicam apenas 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 para Xcode: npx expo run:ios --no-build-cache
• Limpe o cache do Gradle para Android: cd android && ./gradlew clean

Organização

• Revise as notas de lançamento para a versão do SDK de destino em https://expo.dev/changelog
• Se estiver usando Expo SDK 54 ou posterior, certifique-se de que react-native-worklets esteja instalado — isso é necessário para que react-native-reanimated funcione.
• Habilite o React Compiler no SDK 54+ adicionando "experiments": { "reactCompiler": true } ao app.json — é estável e recomendado
• Exclua sdkVersion de app.json para deixar o Expo gerenciá-lo automaticamente
• Remova pacotes implícitos de package.json: @babel/core, babel-preset-expo, expo-constants.
• 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 Descontinuados

Ao migrar pacotes descontinuados, atualize todo o uso do 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 excluiu pacotes:

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

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

Removendo patches

…