Como criar Widgets Android no Expo com React Native
Desde a instalação da biblioteca até o deploy do widget nativo: o passo a passo oficial para trazer widgets Android de verdade para seu app em Expo.
Por que isso é importante
Ter um widget Android de verdade integrado ao seu app Expo pode ser o diferencial que coloca seu aplicativo no radar dos usuários, gera engajamento diário e amplia as possibilidades do seu produto no ecossistema mobile. Com a nova biblioteca React Native Android Widget, integração agora é possível, mesmo para quem usa Expo.
Widgets Android nativos agora no Expo: impossível ignorar
Até recentemente, criar widgets nativos Android dentro de um app Expo era um enorme desafio. Agora, não só é possível, como ficou mais fácil do que nunca. A biblioteca React Native Android Widget permite todo o processo direto do seu ambiente Expo, sem eject ou gambiarras. O resultado? Recursos visuais de destaque, interação direta no home screen e uma experiência premium para qualquer usuário Android.
Do zero ao widget: comece seu projeto
Basta abrir o terminal, criar um novo projeto com npx create-expo-app e dar um nome representativo, como “android-widget-app”. Feito isso, basta abrir no VSCode e conectar seu dispositivo Android físico ou emulador para acompanhar cada etapa.
⚠️Atenção
Testar com um dispositivo físico agiliza muito a depuração de widgets! Use o Android Studio para conectar seu aparelho ou configurar um emulador.
Instalação da biblioteca React Native Android Widget
No terminal do projeto, rode npm install react-native-android-widget (ou yarn add). Confirme a instalação no package.json, verificando se “react-native-android-widget” aparece na lista de dependências.
ℹ️Atenção
Uma das maiores vantagens: você desenvolve e testa widgets sem sair do ambiente Expo. Não é preciso ejetar o app!
Exemplo: criando seu primeiro Widget “Hello”
Crie um diretório widget/ na raiz do seu projeto e dentro dele o arquivo HelloWidget.tsx. Utilize componentes oferecidos pela lib, como WidgetFlex e WidgetText, para montar a interface do widget. A renderização e o estilo seguem a lógica básica do React Native, porém são mapeados internamente para código nativo Android.
Como visualizar o widget dentro do próprio app (sem recompilar!)
Use o WidgetPreview, componente da biblioteca que exibe instantaneamente o layout do seu widget dentro do próprio app. Basta importar, adicionar à tela e iterar no visual do widget sem recompilar o projeto a cada ajuste.
✅Atenção
Utilizar WidgetPreview acelera muito o workflow! Mas lembre-se: a experiência final no Android pode ter pequenas diferenças de renderização.
Registrando eventos do widget com regras nativas
Implemente o task handler específico dos widgets criando, por exemplo, o arquivo widgetTaskHandler.ts. Nele, defina objetos e funções responsáveis por lidar com eventos como adicionar, atualizar, redimensionar, deletar ou clicar no widget — tudo nativo!
⚠️Atenção
O nome registrado do widget dentro do handler precisa ser idêntico ao nome registrado no plugin de configuração, ou seu widget não funcionará.
Integrando com o entrypoint customizado do Expo Router
Para que os widgets funcionem corretamente, altere o package.json para apontar main para index.ts (substituindo o padrão do Expo Router). No arquivo index.ts, importe o Router do Expo e registre o handler do widget logo após a app ser inicializada.
Configurando o widget no app.json (ou app.config.js)
Adicione o plugin react-native-android-widget na seção plugins do app.json, incluindo informações como nome do widget, preview/image, largura mínima e máxima, descrição e outros parâmetros. Isso torna o registro do widget visível no menu de widgets do Android.
ℹ️Atenção
Cada widget deve possuir um nome único e uma imagem de preview. O preview mais comum usa o ícone do app dentro de assets/icon.png.
Primeiro deploy: build e execução real no Android
Com tudo pronto, rode npx expo prebuild --platform android. Isso gera o projeto nativo necessário. Em seguida, execute npx expo run:android para instalar o app (com o widget) no dispositivo — pronto para testar no menu de widgets do Android.
Corrigindo erros comuns de preview e compilador
Alguns projetos usam o React Compiler que pode conflitar com o sistema nativo dos widgets. Para evitar erros, adicione uma configuração específica no arquivo babel.config.js. Veja detalhes na documentação ou no repositório de exemplo do tutorial.
❌Atenção
Preview quebrando? Confira se o React Compiler está ativado, ajuste o Babel e reinicie o projeto antes de prosseguir.
Testando e usando seu primeiro widget Android
Com o app instalado, vá até a home do Android, pressione e segure, escolha “widgets” e adicione seu widget personalizado. Toque, redimensione e veja o resultado em tempo real.
Expandindo: widget contador avançado e interativo
Depois do “Hello Widget”, crie um novo módulo, como CounterWidget.tsx. Exemplo perfeito por envolver estado próprio, personalização, diferentes layouts e possibilidade de receber configurações e propriedades diretamente da tela de ajustes do app — tudo refletido no widget.
⚠️Atenção
Widgets podem passar e receber dados (props) do aplicativo, mas certifique-se de serializar valores e validar tipos para evitar bugs.
Customização: tela de configuração dedicada para o widget
Crie uma tela especial no app para que usuários possam decidir background, cor, conteúdo do widget ou outras opções. A integração utilizando as propriedades do widget permite criar experiências ricas e aderentes à identidade do seu produto.
Compartilhamento de dados: como sincronizar estado app ↔ widget
Implemente funções de handler para enviar propriedades, resgatar dados atuais do app, atualizar estado do widget e garantir que interações sejam refletidas em ambos os lados. Fique atento ao ciclo de atualização do widget no app.json, ajustando o updatePeriodMilliseconds se necessário.
Desafios, limitações e caminhos para o próximo nível
Nem todos os recursos do React Native estão disponíveis em widgets nativos — componentes visuais, tipografia, estilos e interações precisam respeitar a arquitetura Android. Estude o repositório oficial, veja exemplos prontos e itere. Cyber devs que dominam isso hoje serão os criadores de experiências mobile do amanhã.
Próximos passos: tutorial em vídeo e referências
Quer ver tudo isso rodando na prática? Busque o vídeo citado no início, confira a documentação da biblioteca, explore os repositórios de exemplo e teste novas ideias — o universo dos widgets Android no Expo acabou de abrir. Siga a referência oficial e surpreenda até devs Android nativos!