react-native-executorch: 6 coisas que o README esconde (2026)
O README do react-native-executorch vende a proposta de forma direta: “powered by PyTorch’s ExecuTorch runtime”. Antes de cogitar isso num app de produção, fui conferir na documentação do ExecuTorch o que esse runtime exige de memória e storage (a resposta não está na seção de instalação rápida). Está espalhada entre o Getting Started, a tabela de compatibilidade e, principalmente, nas entrelinhas de quem já lidou com pipeline de build mobile. A ideia de que “rodar IA on-device em React Native” é trocar uma chamada de fetch por um import de lib e seguir o fluxo normal desmonta assim que você lê o repositório com atenção. Separei seis pontos que mudam a forma como eu avaliaria essa lib antes de prometer “IA local” pra alguém que vai usar o app de verdade.
“Privacy-first on-device”: o que isso garante de verdade e o que é spin de marketing
O README é direto: “zero network calls, full offline capability, and guaranteed privacy. No data ever leaves the device.” É uma afirmação técnica razoável. A inferência mesmo (o cálculo do modelo sobre o input do usuário) roda no aparelho, sem round-trip pra um servidor. Mas “privacy-first” descreve onde a inferência acontece, não o que o app faz com o resultado depois. Se o app transcreve áudio localmente com um modelo de speech-to-text e depois manda o texto transcrito pro backend pra “melhorar a experiência” ou salvar histórico, a privacidade acabou no mesmo segundo em que você chamou outro endpoint.
Tem uma ressalva que o próprio README deixa escapar: o download dos modelos pré-exportados dispara um “anonymous download event” por padrão, e só se desliga explicitamente com setTelemetryEnabled(false). A suposição comum de que “privacy-first” equivale a “zero telemetria” já nasce errada: tem telemetria, é opt-out, não opt-in. Pra um app que lida com dado sensível (saúde, jurídico, financeiro) e precisa documentar conformidade com LGPD, essa linha vai parar na revisão de um DPO, não só do time de engenharia.
Quais modelos cabem no bolso: quantização e o teto de RAM que o runtime impõe
O exemplo do próprio README usa models.llm.LFM2_5_1_2B.DEFAULT, um modelo da família LFM pensado especificamente pra rodar em dispositivo móvel. Não é escolha aleatória: é o porte de modelo que um runtime como o ExecuTorch consegue processar, com quantização, dentro do orçamento de memória de um smartphone, bem diferente do que normalmente roda em servidor com GPU dedicada. A documentação do ExecuTorch (projeto da PyTorch/Meta) trata footprint de memória como requisito de projeto, não como detalhe de rodapé. É parte do motivo de existir um formato .pte exportado e otimizado em vez de carregar um checkpoint genérico.
Na prática, o catálogo de modelos pré-exportados que o react-native-executorch disponibiliza na coleção da Software Mansion no Hugging Face não é “qualquer modelo que você goste”. É uma curadoria do que já foi validado pra caber no runtime sem estourar o orçamento de memória do device. Se você quer trazer seu próprio .pte (o README permite isso explicitamente), o trabalho de quantizar, exportar e validar que aquele modelo não mata o processo por falta de RAM fica inteiramente com você. Não tem atalho documentado pra isso no Getting Started; é trabalho de engenharia de ML antes mesmo de tocar em React Native.
iOS e Android não são o mesmo runtime: onde o comportamento diverge e por quê
A tabela de “Key Features” do README lista quatro delegates de aceleração: XNNPACK (CPU, multiplataforma), Core ML e MLX (exclusivos de Apple Silicon) e Vulkan (GPU Android). Isso já entrega a notícia: você não está escrevendo código pra um runtime mobile único, está escrevendo código que vai ser executado por caminhos de hardware completamente diferentes dependendo da plataforma.
É comum testar tudo no simulador iOS durante o desenvolvimento, porque é rápido, não precisa de cabo, não precisa de device físico emparelhado. O simulador roda em CPU, via XNNPACK, sem acesso ao Neural Engine real da Apple. Quando esse mesmo fluxo vai pra um iPhone físico com Core ML habilitado, a diferença de latência pode ir em qualquer direção dependendo do modelo e de como o delegate foi configurado. O ponto não é que vá ficar mais rápido ou mais lento de forma previsível: é que simulador e device físico não são o mesmo ambiente de execução, algo que não aparece nos primeiros passos documentados. Quem valida latência só no simulador está validando um comportamento que o usuário final nunca vai ver.
Os requisitos mínimos reforçam essa divergência: versões recentes de iOS de um lado, Android com uma API mínima relativamente alta do outro. Faixas etárias de SO bem diferentes, sinal de que o time da Software Mansion fez concessões distintas em cada plataforma pra viabilizar o runtime.
O custo que não aparece no Getting Started: tamanho de binário e tempo de build
Nenhuma linha do README fala sobre quanto a lib adiciona ao tamanho final do .ipa ou do .apk. Isso é esperado (README de lib normalmente foca em API, não em métrica de build), mas é justamente a informação que separa “funciona no meu Simulator” de “funciona na App Store Connect”. Quem já levou um aviso de “app size” ou um alerta de limite de download sem Wi-Fi no processo de review da Apple sabe que esse tipo de estouro costuma aparecer tarde demais, só na hora de submeter o build, quando já não dá pra reorganizar a arquitetura do zero. Google Play também sinaliza apps grandes direto na Play Console, antes mesmo de qualquer usuário baixar.
A arquitetura que o README descreve mitiga isso parcialmente: os modelos pré-exportados são baixados via Hugging Face em runtime, não embarcados no bundle (dá pra ver isso no próprio trecho de código de exemplo, que mostra session.downloadProgress como parte do estado do hook). O binário da lib pode ser relativamente contido, mas o app como experiência completa carrega um download pesado de modelo que precisa ser gerenciado (cache, fallback sem rede, UX de loading), e isso é trabalho de arquitetura de app, não de npm install.
Tem outro custo que o README deixa explícito logo na seção de requisitos: é obrigatório ter a New Architecture do React Native habilitada e react-native-worklets/plugin configurado como último item do Babel. Isso não é trivial em um app legado que ainda roda a arquitetura antiga. É migração de infraestrutura antes de qualquer linha de IA entrar em cena.
NPU, GPU, CPU: a aceleração de hardware é automática ou exige configuração manual
O README nomeia os quatro delegates (XNNPACK, Core ML, MLX, Vulkan) na seção de features, mas não detalha ali se a escolha do delegate é automática por plataforma ou se exige configuração explícita do dev. Esse nível de detalhe fica pra documentação completa em docs.swmansion.com/react-native-executorch, que o próprio projeto aponta como referência para “architecture deep dives”. O que dá pra afirmar com segurança, só pelo que está documentado publicamente, é que a lib expõe múltiplos caminhos de hardware, e a suposição de “vai usar automaticamente o melhor hardware disponível” precisa ser verificada na documentação completa antes de virar premissa de arquitetura. Não dá pra tratar como garantia só porque a feature existe no README.
Isso importa porque o comportamento de fallback (o que acontece se o device não suporta Core ML ou Vulkan) determina se seu app degrada graciosamente num aparelho mais antigo ou simplesmente trava. Com requisitos mínimos de SO relativamente recentes, o próprio projeto já corta parte do problema, mas corta também uma fatia relevante do parque de devices Android ainda em uso, segundo qualquer pesquisa de fragmentação de versão do próprio Android (Google publica esses números no Android Studio via Play Console).
Quando vale trocar API por inferência local (e quando a nuvem ainda ganha disparado)
Pelo que o projeto documenta, o react-native-executorch faz sentido claro em alguns cenários: apps que precisam funcionar 100% offline (campo, indústria, áreas sem conectividade confiável), apps onde o dado de entrada é sensível o bastante pra justificar o esforço de engenharia de nunca sair do device, e tarefas pontuais e bem definidas (OCR, detecção de objeto, transcrição de áudio curto) onde um modelo pequeno quantizado dá conta do recado sem exigir orquestração de contexto longo.
Onde a nuvem ainda ganha disparado: qualquer caso que precise de modelo grande, contexto extenso, ou atualização de modelo sem exigir que o usuário baixe um novo build. Trocar um modelo de LLM que roda num endpoint de API por um .pte embarcado significa que toda melhoria de modelo vira ciclo de update de app, e update de app passa por review de loja, adoção gradual do usuário, e o risco real de parte da sua base ficar presa numa versão de modelo desatualizada por meses. Pra prototipagem rápida ou produto que muda de modelo toda semana, isso é fricção que a nuvem simplesmente não tem.
Minha régua pessoal pra decidir é essa: se o requisito é “funciona sem internet” ou “dado nunca sai do aparelho”, o esforço de infraestrutura que o ExecuTorch runtime exige compensa. Se o requisito é só “quero economizar custo de API”, provavelmente ainda compensa mais negociar um plano melhor com o provedor de nuvem do que reescrever o pipeline de build do app inteiro.
Checklist antes de aprovar isso num roadmap
Se você chegou até aqui pensando em colocar react-native-executorch num app real, essa é a lista que eu rodaria antes de qualquer estimativa:
- Testou o fluxo completo num device físico de cada plataforma, não só no simulador/emulador?
- Mediu o tamanho final do
.ipa/.apkcom o modelo baixado, não só o peso da lib no bundle? - Confirmou
setTelemetryEnabled(false)se o requisito de privacidade for levado a sério? - Validou que o app já roda na New Architecture, ou orçou essa migração separadamente?
- Tem um plano de fallback pra devices que não atendem a versão mínima de SO exigida?
- Sabe quem vai manter o pipeline de quantização e exportação
.ptese decidir fugir do catálogo pronto da Software Mansion?
Nenhum item dessa lista está explícito de forma reunida no README. Cada um aparece espalhado entre seções diferentes, ou simplesmente não aparece, e é exatamente aí que mora o risco de assumir compromisso de produção sem ter lido a documentação completa até o fim.