Como criar Widgets Android no Expo com React Native

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.

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.

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.

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!

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.

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.

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.

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!

Perguntas frequentes

Como adicionar widgets Android?

Widget provider, update period e limites de UI. Teste em device real.

Expo facilita?

Depende do módulo/config nativa da sua SDK.

iOS junto?

APIs diferentes. Não copie 1:1.

IA ajuda?

Rascunha boilerplate. Você valida lifecycle.

Continue explorando