Esqueleto Expo genérico e reutilizável para novos apps: já vem com login/auth,
persistência de sessão, uma camada offline básica e navegação funcionando.
A ideia é copiar esta pasta para começar um projeto novo e só substituir as
telas de exemplo (módulo Home) pela regra de negócio real.
npm install
cp .env.example .env # ajuste EXPO_PUBLIC_API_URL para a sua API
npx expo start
Abra no Expo Go (Android/iOS) ou pressione w para rodar no navegador.
core/ camada compartilhada — NÃO deve conter regra de negócio
api/client.js cliente HTTP genérico (apiFetch)
auth/ AuthContext (login/logout/sessão) + authApi
config/env.js leitura da URL da API
navigation/ RootNavigator (stack com abas + telas empilhadas),
AppTabs (bottom tabs pós-login), navigationRef
(navegar fora da árvore de componentes) e
screenTitles (título automático do AppHeader por rota)
offline/ outbox + cache sobre AsyncStorage + OfflineContext +
SyncScreen (UI para ver/gerenciar a fila offline)
notifications/ NotificacoesScreen — central de notificações in-app
services/storage.js SecureStore (nativo) / localStorage (web)
services/pushNotifications.js + pushApi.js registro de push (Expo Push)
services/notificacoesApi.js lista/marcar-lida das notificações in-app
styles/common.js tokens de estilo reutilizáveis entre telas
theme/colors.js paleta de cores
ui/ componentes de UI (AppHeader, Footer, ErrorView, ...)
utils/ helpers puros (responsive, formatters, dateHelpers)
modules/
Auth/ telas de login e recuperação de senha
Home/ MÓDULO DE EXEMPLO — troque pelas telas do app real
(inclui TrocarSenhaScreen, que é genérica e pode ficar)
config/
modules.config.js agrega as abas de cada módulo em getAppTabs()
Imports: código dentro de core/ usa caminhos relativos entre si; qualquer
outro lugar usa os aliases @core, @modules, @config, @assets
(configurados em metro.config.js e jsconfig.json).
- Crie
modules/<Nome>/{screens,styles,config}. - Em
modules/<Nome>/config/module.config.js, exportetabs(mesmo formato demodules/Home/config/module.config.js) se as telas devem virar abas, ouroutes(formato demodules/Auth/config/module.config.js) se for um stack separado (ex.: fluxo antes do login). - Se for aba pós-login, importe e faça o spread em
config/modules.config.js(getAppTabs).
O módulo Home é só um exemplo — pode ser apagado/substituído inteiramente.
O app assume um backend REST genérico com token Bearer. Ajuste
core/auth/authApi.js e core/api/client.js se o seu backend usar outro
formato.
POST /auth/login— body{ login, senha }→200 { token, user }(qualquer erro deve retornar status não-2xx e, se possível,{ message })POST /auth/logout— headerAuthorization: Bearer <token>POST /auth/trocar-senha— headerAuthorization: Bearer <token>, body{ senha_atual, senha, confirmacao }(usado pormodules/Home/screens/TrocarSenhaScreen.js)POST /push/registrar-token/POST /push/remover-token— headerAuthorization: Bearer <token>, body{ token, plataforma }(usado porcore/services/pushNotifications.js; veja a seção "Push Notifications")GET /notificacoes→200 { notificacoes: [{ id, tipo, titulo, mensagem, data_criacao, lida }] };POST /notificacoes/marcar-lida/:id;POST /notificacoes/marcar-todas-lidas— usados porcore/notifications/NotificacoesScreen.js(histórico in-app do que foi enviado por push, com lida/não lida)- Demais chamadas autenticadas: header
Authorization: Bearer <token>, feitas viaapiFetch(path, options, token)(core/api/client.js).
user é armazenado como veio do backend e fica disponível via useAuth()
(core/auth/AuthContext.js). Ajuste os campos usados nas telas de exemplo
(modules/Home/screens/PerfilScreen.js usa user.nome/user.email) para o
formato real do seu backend.
O app segue o padrão outbox (fila de escrita) + cache (leitura),
tudo sobre AsyncStorage, em core/offline/. É a parte do esqueleto que
mais vale entender antes de expandir, porque é fácil usar errado e achar
que "funciona offline" quando na verdade só funciona online.
Quatro peças, cada uma com uma responsabilidade:
outbox.js— fila de requisições de escrita pendentes (POST/PUT/DELETE). Cada item tem{ id, endpoint, method, body, contentType, label, status, error, tries, createdAt }.statuscomeça em'pending'e vira'error'se o servidor recusar a requisição (ex.: validação falhou) — fica só em'pending'enquanto o problema for falta de rede.contentTypeé opcional: só use quando obodyjá é o payload final pronto para trafegar como está (ex.:FormDatade um upload) — veja "Enfileirar um upload" abaixo.cache.js— cache simples de leitura:cacheSet(key, value)/cacheGet(key)/cacheRemove(key), com timestamp (savedAt) de quando foi salvo. Serve para mostrar o último dado conhecido quando não há conexão.syncManager.js— a funçãosincronizar(token)percorre os itenspendingdo outbox, chamaapiFetchpara cada um, remove os que deram certo, marca comoerroros que o servidor rejeitou, e para imediatamente (sem marcar erro) no primeiro item que falhar por falta de rede (err.isNetwork) — evita marcar tudo como erro só porque a conexão caiu no meio da sincronização.OfflineContext.js— expõe tudo isso viauseOffline():itens,pendentes(contagem),syncing,sync(token),remover(id),limparErros(). É usado tanto pelo resumo emmodules/Home/screens/ConfiguracoesScreen.js(contagem + botão rápido de sync) quanto porSyncScreen.js— tela completa (empilhada sobre as abas, vercore/navigation/RootNavigator.js) que lista cada item pendente/com erro, com opção de descartar individualmente ou todos com erro de uma vez.
Hoje a sincronização é manual (botão "Sincronizar agora") — não há listener de reconexão de rede nem sync em background. Isso é intencional para manter o esqueleto simples; veja "Como expandir" abaixo para adicionar isso quando o app real precisar.
Há um exemplo funcionando em modules/Home/screens/HomeScreen.js ("Nota
rápida" → "Salvar offline"): salve algo lá e depois abra Ajustes > Ver fila
detalhada (SyncScreen) para ver o item pendente e tentar sincronizar.
Enfileirar uma escrita que deve sobreviver offline (em vez de chamar
apiFetch direto na tela):
import { outboxEnqueue } from '@core/offline/outbox';
await outboxEnqueue({
endpoint: '/tarefas',
method: 'POST',
body: { titulo: 'Nova tarefa' },
label: 'Nova tarefa', // texto mostrado na UI de pendências, se você exibir
});O item fica na fila até alguém chamar useOffline().sync(token) (o botão
em Configurações já faz isso) — em caso de sucesso ele some da fila
sozinho.
Enfileirar um upload (multipart) que deve sobreviver offline — passe
contentType e um body já pronto (não serializado em JSON):
const form = new FormData();
form.append('arquivo', { uri, name: 'foto.jpg', type: 'image/jpeg' });
await outboxEnqueue({
endpoint: '/uploads',
method: 'POST',
body: form,
contentType: 'multipart/form-data',
label: 'Upload de foto',
});syncManager.js detecta contentType e reenvia o body como está (sem
JSON.stringify) quando a sincronização rodar.
Cachear uma leitura para exibir algo quando estiver offline:
import { cacheGet, cacheSet } from '@core/offline/cache';
import { apiFetch } from '@core/api/client';
async function carregarTarefas(token) {
try {
const data = await apiFetch('/tarefas', {}, token);
await cacheSet('tarefas', data);
return data;
} catch (err) {
if (err.isNetwork) {
const cached = await cacheGet('tarefas');
if (cached) return cached.value; // dado desatualizado, mas mostra algo
}
throw err;
}
}- Sync automático ao reconectar: instale
@react-native-community/netinfoe, noOfflineProvider(core/offline/OfflineContext.js), assineNetInfo.addEventListenerchamandosync(token)quandoisConnectedvirartrue. Hoje isso depende do usuário apertar o botão. - Ações otimistas: para a UI não "travar" esperando rede, atualize o
estado local/tela imediatamente ao enfileirar (
outboxEnqueue) e só reverta se a sincronização depois marcar aquele item como'error'. - Ler
err.isNetworknas telas: qualquer erro de rede lançado porapiFetch(core/api/client.js) temisNetwork: true— use isso para decidir quando cair paracacheGetem vez de mostrar uma tela de erro. - Retry com backoff:
outbox.jsjá guardatries(quantas vezes tentou); dá pra usar esse número para espaçar novas tentativas automáticas em vez de tentar sempre no próximosync(). - Criptografar o conteúdo sensível: outbox e cache guardam tudo em
texto puro no
AsyncStorage(ver seção Segurança). Se o app real manipular dados sensíveis offline, considere cifrar obody/valueantes deoutboxEnqueue/cacheSete decifrar ao sincronizar/ler. - Separar filas por domínio: se o app tiver muitos tipos de escrita
offline, adicione um campo (ex.:
tipo) ao item do outbox e filtre por ele nas telas — a estrutura de dados já suporta campos extras. - Não precisa de offline? Apague
core/offline/, removaOfflineProviderdeApp.jse o bloco de sincronização demodules/Home/screens/ConfiguracoesScreen.js.
Em app.json, ajuste expo.name, expo.slug e expo.android.package /
expo.ios.bundleIdentifier. Troque os ícones em assets/ pelos do novo app.
core/services/pushNotifications.js + pushApi.js implementam o fluxo
Expo Push (que usa FCM no Android e APNs no iOS por baixo dos panos):
pedir permissão, gerar o token do dispositivo e registrá-lo no backend.
core/navigation/RootNavigator.js já chama registrarPushToken(token)
automaticamente (best-effort, nunca trava login) assim que há uma sessão
válida.
Sem configuração adicional, a chamada é um no-op seguro — sem
expo.extra.eas.projectId em app.json, registrarPushToken retorna
null e não faz nada. Para habilitar de fato:
npx eas init(cria o projeto no EAS e preencheextra.eas.projectIdemapp.json).- Para Android, configure o Firebase (FCM) via
eas credentialsougoogle-services.json— veja a documentação do Expo sobre "Push notifications setup". - Ajuste os endpoints em
core/services/pushApi.js(/push/registrar-token,/push/remover-token) para o contrato real do seu backend.
Tocar numa notificação recebida ainda não navega para lugar nenhum —
trate Notifications.addNotificationResponseReceivedListener (ex.: em
App.js) se o app precisar disso.
Não precisa de push? Remova a chamada em RootNavigator.js, apague
core/services/pushNotifications.js/pushApi.js e as dependências
expo-notifications/expo-device/expo-constants do package.json.
core/notifications/NotificacoesScreen.js é independente do push acima —
é só uma lista (com lida/não lida) do que o backend guardou como
notificação do usuário, acessível pelo ícone de sino em
modules/Home/screens/HomeScreen.js. Ajuste TIPO_ICONES
(NotificacoesScreen.js) para dar um ícone/cor específico a cada tipo de
notificação do seu domínio — tipos sem entrada usam o ícone padrão.
Não precisa? Apague core/notifications/,
core/services/notificacoesApi.js, a rota Notificacoes em
RootNavigator.js e o botão de sino em HomeScreen.js.
- HTTPS obrigatório em produção:
core/config/env.jsrecusa subir (throw) seEXPO_PUBLIC_API_URLnão começar comhttps://fora de desenvolvimento local. Em dev,http://só é aceito paralocalhost/127.0.0.1/rede local — qualquer outro endereçohttp://gera um aviso no console. - Token de sessão: guardado com
expo-secure-store(Keychain/Keystore criptografado pelo SO) em iOS/Android. No Web cai paralocalStorage(core/services/storage.js), que é acessível por qualquer script rodando na página — se o app for levado a sério na web, considere trocar para autenticação via cookiehttpOnly(exige mudança no backend). - Auto-logout em sessão inválida:
apiFetch(core/api/client.js) aciona automaticamentesignOut()quando uma chamada autenticada recebe401/403— o usuário não fica "preso" numa sessão com token expirado ou revogado. EXPO_PUBLIC_*não é secreto: qualquer variável com esse prefixo fica embutida em texto no bundle final do app (visível a quem descompilar). Nunca coloque API keys/secrets ali — só valores que já seriam públicos.- Autofill nativo: os campos de usuário/senha usam
textContentType/autoCompletecorretos para que o gerenciador de senhas do sistema (Keychain/Google Password Manager) funcione — incentiva senhas únicas e fortes em vez de desabilitar o autofill. - Outbox offline em texto puro:
core/offline/outbox.jsguarda os corpos das requisições pendentes noAsyncStorage(não criptografado, diferente do token). Se o app real for lidar com dados sensíveis offline, avalie criptografar o conteúdo antes de salvar ou remover a camada offline.
Quando a API real for construída, para manter o mesmo padrão de segurança fim-a-fim ela deve garantir:
- HTTPS obrigatório (HSTS habilitado), sem fallback para HTTP.
- Tokens de curta duração (ex.: JWT de 15–60 min) com refresh token
rotativo, em vez de um token único de vida longa — reduz o estrago de um
token vazado. O client já está pronto para tratar
401reativamente (auto-logout); se adotar refresh token, é só trocar a implementação designIn/apiFetchpara tentar um refresh antes de deslogar. - Rate limiting / lockout no login (por IP e por conta) contra força-bruta, e respostas de erro genéricas ("credenciais inválidas", nunca "usuário não existe" vs. "senha errada").
- Hash de senha com algoritmo lento (bcrypt/argon2), nunca em texto puro nem hash rápido (MD5/SHA1/SHA256 puro).
- CORS restrito à(s) origem(ns) real(is) do app (e do painel web, se
houver), nunca
*em endpoint autenticado. - Validação de entrada no servidor (nunca confiar apenas na validação do app) e queries parametrizadas (proteção contra SQL/NoSQL injection).
- Headers de segurança em qualquer superfície web associada (CSP,
X-Content-Type-Options: nosniff,X-Frame-Options, etc.). - Logs sem dados sensíveis — nunca logar senha, token completo ou corpo de requisições de auth.
Desenvolvido e mantido por: @codebyazeredo