upgrading-expo

Visão geral da skill upgrading-expo

O que a skill upgrading-expo faz

A skill upgrading-expo ajuda você a planejar e executar upgrades do Expo SDK com menos pontos cegos do que um prompt genérico do tipo “como faço upgrade do Expo?”. Ela é focada no trabalho real: atualizar pacotes centrais, corrigir drift de dependências, limpar caches antigos e identificar mudanças incompatíveis comuns em torno de React, New Architecture, Native Tabs e migrações de expo-av.

Quem deve usar upgrading-expo

Esta upgrading-expo skill é mais indicada para desenvolvedores frontend, equipes de React Native e agentes de IA que mantêm um app Expo já existente. Ela é mais útil quando você já tem um projeto e precisa de um caminho prático de upgrade, e não apenas de resumos de release notes.

Casos em que ela se encaixa melhor:

• Upgrade entre versões recentes do Expo SDK
• Corrigir quebras de instalação ou de runtime após expo install --fix
• Migrar para longe de pacotes alterados ou divididos, como expo-av
• Verificar se mudanças específicas do SDK, como React 19 ou Native Tabs, afetam sua base de código

O trabalho real que precisa ser resolvido

Quem avalia upgrading-expo for Frontend Development normalmente quer responder três perguntas rapidamente:

1. Qual sequência de comandos devo rodar primeiro?
2. Quais breaking changes têm mais chance de afetar meu app?
3. Que arquivos ou padrões devo inspecionar antes de perder tempo depurando?

Essa skill é valiosa porque reúne essas decisões em um só lugar e as conecta a referências concretas de migração.

O que diferencia essa skill de um prompt genérico de upgrade

Um prompt comum pode sugerir “atualize o Expo e rode doctor”. A skill upgrading-expo vai além ao destacar tópicos de migração ligados à versão diretamente do repositório, incluindo:

• padrões da New Architecture no SDK 53+
• mudanças do React 19 no SDK 54
• configuração do React Compiler no SDK 54+
• mudanças na API de Native Tabs no SDK 55
• caminhos de substituição de expo-av para áudio e vídeo

Isso a torna melhor para trabalho de upgrade direcionado do que um prompt amplo de troubleshooting em React Native.

O que saber antes de instalar

Esta skill é mais orientada a orientação do que a automação. Ela não inclui scripts que inspecionam seu repositório por você. O valor dela está no fluxo de upgrade curado e nos documentos de referência que você aplica à sua própria base de código. Se você quer um migrador de um clique, não é isso. Se quer um checklist de upgrade com alto sinal e exemplos concretos de migração, ela é uma ótima escolha.

Como usar a skill upgrading-expo

Contexto de instalação da upgrading-expo

Se o seu ambiente de IA oferece suporte a Skills, instale o repositório de skills do Expo e invoque upgrading-expo a partir dele. Um padrão comum é:

npx skills add https://github.com/expo/skills --skill upgrading-expo

Se o seu toolchain usa outro carregador de skills, aponte para o caminho no repositório:
plugins/expo/skills/upgrading-expo

Comece pelos arquivos certos do repositório

Para um uso prático de upgrading-expo, leia estes arquivos nesta ordem:

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

Essa ordem de leitura espelha os bloqueios de upgrade mais comuns: primeiro mudanças de arquitetura e de React; depois migrações no nível de recursos.

Use primeiro a sequência principal de upgrade

O fluxo base de upgrade da skill é curto e vale a pena seguir antes de partir para uma depuração mais profunda:

npx expo install expo@latest
npx expo install --fix
npx expo-doctor
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Por que isso importa:

• expo@latest alinha o SDK
• --fix reconcilia as versões dos pacotes gerenciados pelo Expo
• expo-doctor detecta problemas de compatibilidade cedo
• limpar cache remove estado antigo do Metro/nativo que pode se passar por bug de upgrade

Se você estiver em Linux ou não usar Watchman, adapte a limpeza conforme o seu ambiente.

Saiba quando usar versões preview

A skill também documenta builds beta do Expo via versões .preview em @next. Isso é útil se você estiver validando um SDK futuro ou testando uma correção que ainda não chegou ao canal stable.

npx expo install expo@next --fix

Use isso apenas de forma intencional. Upgrades para preview não são uma boa opção padrão para apps em produção, a menos que você esteja testando explicitamente uma pre-release.

Forneça as informações de que a skill realmente precisa

Os melhores prompts para o upgrading-expo guide incluem seu estado atual e seu objetivo. Forneça à skill:

• versão atual do Expo SDK
• package manager
• se você usa Expo Go ou development builds
• se você roda prebuild
• pacotes principais: expo-router, expo-av, react-native-reanimated, módulos nativos customizados
• erros atuais de instalação, build ou runtime
• falhas específicas de plataforma em iOS, Android ou web

Sem esse contexto, a resposta tende a ficar genérica.

Transforme um objetivo vago em um prompt forte

Prompt fraco:

Upgrade my Expo app.

Prompt melhor:

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

Por que isso funciona:

• informa o SDK de origem e o de destino
• lista pacotes de maior risco
• pede uma saída priorizada, e não conselho genérico

Relacione seu app aos guias de referência

As referências do repositório são mais úteis quando você as relaciona deliberadamente à sua superfície de dependências:

• Usa expo-av para som ou gravação? Leia references/expo-av-to-audio.md
• Usa expo-av para vídeo? Leia references/expo-av-to-video.md
• Vai atualizar para SDK 55 com expo-router/unstable-native-tabs? Leia references/native-tabs.md
• Está entrando no SDK 53+ ou 54+ com módulos nativos? Leia references/new-architecture.md
• Está no SDK 54? Verifique tanto references/react-19.md quanto references/react-compiler.md

É aqui que a skill entrega ganho real de informação em comparação com uma passada rápida pelo repositório.

Fique de olho nas áreas de upgrade de maior risco

Na prática, estes são os pontos de quebra mais comuns destacados pela skill:

• desalinhamento de versões de pacotes após subir o SDK
• incompatibilidade com a New Architecture em módulos nativos mais antigos
• mudanças de configuração do Reanimated, incluindo react-native-worklets no SDK 54+
• mudanças de API do React 19 no código do app ou de bibliotecas
• migrações de expo-av para expo-audio e expo-video
• mudanças de UI no nível do router em Native Tabs

Se o seu app usa qualquer um desses itens, peça à skill um checklist de migração direcionado em vez de um resumo geral de upgrade.

Use um fluxo em duas passagens

Um bom padrão de uso do upgrading-expo é:

1. Pedir um plano de upgrade com base nas suas versões e dependências
2. Rodar os comandos
3. Trazer de volta os erros exatos e pedir um plano de correção mais focado

Essa skill funciona melhor em triagem estruturada quando você retorna com saídas concretas de expo-doctor, TypeScript, Metro ou builds nativos.

Verifique os pontos no estilo release notes que a skill sugere

O checklist de breaking changes da skill aponta para áreas práticas de revisão:

• APIs removidas
• caminhos de import alterados
• mudanças em módulos nativos que exigem prebuild
• regressões em câmera, áudio e vídeo
• regressões de navegação

Isso significa que sua revisão de código não deve parar em package.json. Pesquise na base de código imports e componentes afetados antes de executar o app.

Use com cuidado em projetos com prebuild e código nativo

Se o seu app usa módulos nativos customizados ou config plugins, a upgrading-expo skill continua sendo útil, mas você deve esperar trabalho extra fora das referências em markdown. Nesses projetos, peça à skill para separar:

• tarefas de migração só em JS
• tarefas de regeneração de prebuild
• verificações de compatibilidade de dependências nativas

Essa separação reduz a confusão durante o upgrade.

FAQ da skill upgrading-expo

upgrading-expo é boa para iniciantes?

Sim, se você já tiver um projeto Expo e conseguir compartilhar detalhes básicos do projeto. Ela não é um tutorial completo de Expo. É um guia focado em upgrade, então iniciantes tendem a obter melhores resultados quando informam a versão atual do SDK, os erros e as principais dependências.

Qual é o limite de atuação da skill upgrading-expo?

A skill ajuda com planejamento de upgrade, ordem dos comandos e hotspots conhecidos de migração. Ela não inspeciona automaticamente todo o seu repositório nem garante compatibilidade com qualquer biblioteca nativa de terceiros. Em casos de quebra nativa mais profunda, você ainda pode precisar da documentação específica do pacote e de issues no GitHub.

Em que upgrading-expo é diferente de apenas pedir a um LLM para atualizar o Expo?

A principal diferença é a curadoria. A upgrading-expo skill direciona o modelo para referências de migração específicas do Expo que um prompt genérico pode deixar passar, especialmente em torno de expo-av, React 19, React Compiler, Native Tabs e comportamento da New Architecture.

Quando não devo usar upgrading-expo?

Evite usar se:

• você está começando um app Expo do zero em vez de atualizar um existente
• seu problema não tem relação com upgrades de SDK
• você precisa de um codemod automatizado ou de uma ferramenta CLI de migração
• seu principal bloqueio é uma única biblioteca nativa de terceiros com passos de migração próprios e muito específicos

upgrading-expo cobre SDKs preview?

Sim. A skill observa que releases beta usam o sufixo .preview e são instalados a partir de @next. Isso ajuda em testes de mudanças futuras, mas upgrades stable continuam sendo a opção mais segura por padrão.

upgrading-expo serve apenas para apps no workflow managed?

Não. Ela é útil tanto para apps Expo no workflow managed quanto para apps baseados em prebuild, mas prebuild e código nativo customizado aumentam a chance de você precisar de verificações manuais extras de compatibilidade.

Como melhorar o uso da skill upgrading-expo

Informe à skill exatamente qual é o salto de versão

A melhoria de maior valor é simples: diga “do SDK X para o SDK Y”, e não apenas “upgrade Expo”. Grande parte do conselho de migração muda de forma material dependendo se você está entrando no SDK 53, 54 ou 55.

Inclua a superfície de pacotes que muda a resposta

Para melhores resultados com upgrading-expo, inclua os pacotes que acionam os documentos de referência:

• expo-av
• expo-router
• react-native-reanimated
• módulos nativos customizados
• qualquer pacote que falhe no expo-doctor

Isso permite que a skill saia de checklists genéricos e passe a orientar pelo impacto mais provável.

Cole diagnósticos reais, não paráfrases

Ruim:

build failed after upgrade

Melhor:

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

Logs exatos ajudam a skill a diferenciar drift de dependências de problemas de migração de API.

Peça uma saída priorizada

Um formato forte de solicitação é:

1. comandos para rodar agora
2. quebras mais prováveis por ordem de probabilidade
3. arquivos/imports para buscar
4. passos de verificação após as correções

Essa estrutura torna o upgrading-expo guide muito mais fácil de executar sob pressão de tempo.

Separe falhas de instalação de migrações de código

Um modo comum de falhar é misturar problemas de instalação de pacotes com mudanças de API no código-fonte. Peça à skill para tratar isso nesta ordem:

• alinhamento de dependências
• saída do doctor
• reset de cache
• migrações no código-fonte
• verificação em runtime

Isso reduz depuração circular.

Peça padrões de busca específicos para a base de código

Uma das melhores formas de melhorar a saída da upgrading-expo skill é pedir alvos de busca no estilo grep. Exemplo:

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

Isso transforma orientação ampla em tarefas acionáveis de revisão de código.

Valide os caminhos de maior risco após a primeira passagem

Depois da primeira tentativa de upgrade, teste especificamente:

• reprodução e gravação de áudio
• reprodução de vídeo
• navegação por abas
• inicialização no Expo Go vs dev build
• qualquer tela que use animações pesadas ou módulos nativos

Essas são as áreas com maior chance de expor problemas de transição de SDK cobertos pela skill.

Itere com prompts de acompanhamento mais estreitos

Não peça repetidamente que a skill resolva o upgrade inteiro. Restrinja o segundo prompt:

• “Focus only on React 19 changes in my shared UI package”
• “Focus only on expo-av video migration”
• “Focus only on New Architecture incompatibilities”

Escopos menores costumam produzir passos de correção mais claros e mais precisos.