Rive no Expo: exige development build (não o Expo Go)

O Rive funciona no Expo Go?

Não. O Expo Go é um app pré-compilado com um conjunto fixo de módulos nativos. A documentação do Rive diz claramente que, como o pacote para React Native contém código nativo personalizado, ele não é compatível com o Expo Go, e você precisa usar um development build.

Um development build é a sua própria versão da ideia do Expo Go: um build de debug do seu app que inclui o expo-dev-client e as bibliotecas nativas que você adicionou. Você continua tendo fast refresh e o menu de desenvolvedor, e as mudanças em JavaScript carregam sem precisar recompilar. Só é preciso recompilar quando as dependências nativas ou os config plugins mudam.

Se aparecer um erro como módulo nativo ausente no momento em que uma tela com Rive é renderizada, quase certamente o app está rodando no Expo Go, e não no seu development build.

Como criar um development build para o Rive?

A partir de um projeto Expo novo ou existente, instale o dev client e o runtime do Rive com npx expo install, que escolhe versões compatíveis com o seu SDK:

npx create-expo-app my-rive-app
cd my-rive-app
npx expo install expo-dev-client
npx expo install @rive-app/react-native react-native-nitro-modules

O novo runtime é construído sobre Nitro Modules, por isso o react-native-nitro-modules é instalado junto. Em seguida, compile e instale o app. Localmente, isso exige Xcode ou Android Studio:

npx expo run:ios
npx expo run:android

Ou deixe o EAS compilar na nuvem e instale em um dispositivo ou simulador:

eas build --profile development --platform ios
eas build --profile development --platform android

Inicie o bundler com npx expo start e abra o projeto no seu development build, não no Expo Go. A partir daí, editar JavaScript funciona normalmente. Quando você adicionar ou alterar pacotes nativos ou config plugins, rode npx expo prebuild --clean (em builds locais) e recompile.

Para renderizar o componente e controlar a state machine, veja a seção de React Native do guia de runtimes do Rive; o código é o mesmo no Expo e no React Native puro.

Qual pacote usar: @rive-app/react-native ou rive-react-native?

Use @rive-app/react-native em projetos novos. A documentação de React Native do Rive apresenta esse pacote como o novo runtime e o rive-react-native como o runtime legado.

A diferença importa para a forma como você controla a animação. O novo runtime suporta Data Binding com view models, e o Rive publicou um cronograma para remover dele os métodos obsoletos de inputs da state machine. O pacote legado usa as APIs de inputs (definir um número, disparar um trigger pelo nome da state machine e do input).

• Arquivo novo com view models: novo runtime, Data Binding.
• App existente no pacote legado com arquivos só com inputs: continua funcionando; planeje a migração para view models antes de atualizar.

O iOS mínimo mais baixo do pacote legado (14.0 contra 15.1) raramente é motivo para escolhê-lo em 2026, já que os SDKs atuais do Expo já miram versões mais novas do iOS.

Os arquivos .riv do Charmotion suportam os dois caminhos: CharacterViewModelMachine com um view model Character (um número mood de 0 a 9 e os triggers success, error, yes, no, enter e exit) para o runtime novo, e CharacterStateMachine com os inputs clássicos equivalentes. Com um único upload, você recebe 17 animações em poucos minutos, além de exportações sob demanda de MP4, GIF e vídeo transparente.

Como corrigir erros de build Android no Expo SDK 53?

O guia de Expo do Rive explica que o SDK Android do Rive exige compileSdkVersion 36 e Android Gradle Plugin 8.9.1 ou posterior, enquanto o Expo SDK 53 usa versões mais baixas por padrão. O sintoma é um erro do Gradle durante o build Android. A solução é aumentar as duas versões por meio de config plugins no app.json:

{
  "expo": {
    "plugins": [
      ["expo-custom-agp", "8.9.2"],
      ["expo-build-properties", {
        "android": { "compileSdkVersion": 36 },
        "ios": { "deploymentTarget": "15.1" }
      }]
    ]
  }
}

Instale os plugins primeiro com npx expo install expo-build-properties e adicione o expo-custom-agp como o guia descreve. Depois, gere novamente os projetos nativos e recompile:

npx expo prebuild --clean
npx expo run:android

SDKs mais novos do Expo talvez já usem essas versões por padrão; confira a página de Expo do Rive para o seu SDK antes de adicionar substituições desnecessárias. Substituir a versão do plugin do Gradle afeta todos os módulos nativos, então recompile e faça um smoke test do app inteiro, não só da tela com Rive.

Qual deployment target do iOS o Rive exige?

O novo runtime exige iOS 15.1 ou posterior, segundo o guia de Expo do Rive. Defina isso explicitamente com expo-build-properties, como no app.json acima, para que o projeto Xcode gerado e o CocoaPods fiquem de acordo:

["expo-build-properties", { "ios": { "deploymentTarget": "15.1" } }]

Se o seu app já mira uma versão mais nova do iOS, mantenha o valor mais alto. Baixá-lo para igualar ao do Rive quebraria outras dependências.

Depois de mudar o target, rode npx expo prebuild --clean antes de npx expo run:ios. Pods desatualizados são o motivo mais comum para uma mudança de target parecer não ter efeito. No EAS, o prebuild limpo acontece em todo build, então basta fazer commit da alteração no app.json.

O guia de Expo do Rive não indica um mínimo equivalente para Android além das configurações de compilação da seção anterior, mas teste na versão mais antiga do Android que seu app suporta, já que a performance de renderização varia mais em aparelhos de entrada.

Posso usar Lottie no Expo Go durante a prototipagem?

Possivelmente. A referência do SDK do Expo já listou o lottie-react-native como incluído no Expo Go, instalado com npx expo install lottie-react-native. Os módulos incluídos mudam entre versões do SDK, então confira a documentação do Expo para a sua versão antes de contar com isso.

Se estiver disponível, o Lottie é um bom substituto enquanto você projeta as telas no Expo Go: um clipe idle em loop no lugar onde o mascote vai ficar. Saiba o que você perde. O Lottie não tem view model no estilo do Rive, então passar de idle para carregamento e depois para sucesso significa trocar arquivos ou segmentos e sincronizar as transições por conta própria. Quando o personagem precisar reagir ao estado do app, migre para um development build e para o Rive.

Uma terceira opção para protótipos é vídeo simples. Um MP4 do personagem, mudo e em loop, roda no Expo Go pelo módulo de vídeo do Expo e dá aos stakeholders uma prévia realista sem nenhuma configuração nativa. Troque pelo componente do Rive quando o development build estiver pronto.

Como incluir o arquivo .riv como asset?

O Metro, bundler usado pelo Expo, só trata extensões de arquivo conhecidas como assets. Se você carrega o arquivo com require("./assets/character.riv"), adicione riv às extensões de asset no metro.config.js:

const { getDefaultConfig } = require("expo/metro-config");

const config = getDefaultConfig(__dirname);
config.resolver.assetExts.push("riv");

module.exports = config;

Reinicie o bundler com npx expo start --clear depois de editar a configuração. Sem esse passo, o Metro tenta interpretar o arquivo binário como JavaScript e falha com um erro de resolução ou de sintaxe.

Outra opção é carregar o arquivo de uma URL. Isso deixa o binário do app menor e permite atualizar o personagem sem lançar uma nova versão, ao custo de uma requisição de rede no primeiro carregamento. Para um mascote que aparece na abertura ou offline, inclua o arquivo no app. De qualquer forma, carregue o arquivo uma vez por tela, e não a cada renderização.

Como rodar o Rive em um app Expo

1. Instale o dev client. Rode npx expo install expo-dev-client.
2. Instale o Rive. Execute npx expo install @rive-app/react-native react-native-nitro-modules.
3. Defina as versões nativas. Adicione expo-build-properties (iOS 15.1 e, no Android, compileSdkVersion 36 no SDK 53) ao app.json.
4. Registre o tipo de asset. Adicione riv a resolver.assetExts no metro.config.js.
5. Build. Execute npx expo prebuild --clean e npx expo run:ios, ou eas build --profile development.
6. Abra no development build. Rode npx expo start e abra o projeto no seu development build, não no Expo Go.

Perguntas frequentes

Dá para adicionar o Rive ao Expo sem fazer eject?

Sim. O Expo não exige mais eject. Development builds e config plugins permitem adicionar pacotes nativos como o @rive-app/react-native sem sair do managed workflow. O npx expo prebuild gera os projetos nativos para você, e o EAS Build pode gerar os binários na nuvem.

Preciso de um Mac para fazer o build do Rive para iOS com Expo?

Não, se você usar o EAS Build, que compila o development build de iOS nos servidores da Expo e entrega um build instalável. Fazer o build localmente com npx expo run:ios exige o Xcode, que só roda no macOS. Instalar em um iPhone físico também exige uma conta de desenvolvedor Apple para a assinatura do app.

O Rive funciona com o Expo Router?

Sim. O Expo Router cuida só da navegação, então uma tela que renderiza o componente do Rive se comporta como qualquer outra. Carregue o arquivo uma vez por tela, libere-o quando a tela for desmontada e evite recriar o componente a cada render, para que a animação não reinicie de forma inesperada.

Respostas rápidas deste guia

• O Rive funciona no Expo Go?
• Por que meu build Android no Expo SDK 53 falha depois de adicionar o Rive?

Fontes

• Adding Rive to Expo, Rive
• React Native runtime, Rive
• Introduction to development builds, Expo
• Customizing Metro, Expo