Melhores Práticas de Arquitetura
Um resumo condensado das 25 melhores práticas mais importantes extraídas de todas as páginas desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 melhores práticas mais importantes extraídas de todas as páginas desta seção.
Comece com fatias de funcionalidades, não microsserviços: Coloque telas, hooks e componentes por área de produto em features/<nome>/ - evolua a estrutura com o tamanho da equipe, não com sistemas distribuídos do dia um.
Mantenha as rotas do Expo Router finas: app/**/*.tsx reexporta telas de funcionalidades e analisa parâmetros - a lógica de negócios pertence a src/features/, não a arquivos de rota.
Exponha uma API pública por funcionalidade: Curadoria de features/<nome>/index.ts - funcionalidades irmãs importam o barril, nunca caminhos profundos em components/ ou model/.
Respeite o fluxo de dependência interna: app → features → entities → shared - código compartilhado nunca importa funcionalidades; entidades nunca importam funcionalidades.
Coloque primitivas compartilhadas em shared/ui: Button e Screen genéricos vivem em shared; UserAvatar específico do domínio vive em entities/user/ui.
Modele substantivos em entidades: Tipos simples e funções puras para User, Order - zero importações de React, testáveis em Node sem um renderizador.
Oculte IO por trás de adaptadores: createOrdersApi(client) e createSecureTokenStorage() - telas e casos de uso nunca chamam fetch ou SecureStore diretamente.
Adicione casos de uso quando os testes precisarem de "seams": Extraia casos de uso signIn, placeOrder quando hooks misturam IO, regras de ramificação e estado de UI - não para cada alternância de botão.
Retorne uniões discriminadas de casos de uso: { ok: false, error: "network" } supera erros lançados através das fronteiras das camadas - os chamadores lidam com falhas explicitamente.
Conecte dependências na raiz de composição: AppServicesProvider em app/_layout.tsx vincula adaptadores de produção - evite singletons no escopo do módulo.
Prefira injeção de fábrica em vez de frameworks de DI: createX(deps) mais contexto React cobrem as necessidades móveis - pule tsyringe/Inversify a menos que a organização exija.
Padrão para TanStack Query para estado do servidor: Listas, detalhes e mutações pertencem ao cache do Query - não slices Redux ou Zustand duplicando dados da API.
Use Zustand para estado pequeno e global do cliente: Carrinho, preferências e cromo da UI - seletores evitam tempestades de re-renderização de listas; não para blobs JSON do servidor.
Mantenha o estado efêmero da UI local: O estado aberto de folhas e o índice do acordeão permanecem na árvore de telas até que uma segunda rota não relacionada genuinamente os necessite.
Coloque o estado da URL nos parâmetros do Expo Router: Filtros e abas via useLocalSearchParams - deep links compartilháveis superam chaves de armazenamento global.
Documente a escolha de navegação em um ADR: Aplicativos Greenfield SDK 57 usam Expo Router por padrão; React Navigation brownfield permanece válido - registre a decisão para onboarding.
Mapeie camadas FSD pragmaticamente: app/, features/, entities/, shared/ - pule widgets/ e pages/ até que um bloco composto se repita entre as rotas.
Imponha limites com ESLint: no-restricted-imports bloqueando @/features/*/components/* - convenções de pasta sozinhas falham com mais de 10 funcionalidades.
Monolito modular antes de multi-app: Um repositório com APP_VARIANT e flags de funcionalidade até que IDs de bundle, conformidade ou cadência de lançamento realmente diverjam.
Separe canais EAS Update por variante: production-consumer vs production-business - o canal errado atualiza a listagem errada da loja.
Centralize a configuração em getAppConfig(): Leia Constants.expoConfig?.extra uma vez - funcionalidades não espalham branches process.env e __DEV__.
Orquestre fluxos entre funcionalidades nas rotas: Passe callbacks onAddToCart de arquivos de rota - funcionalidades não importam stores de funcionalidades irmãs.
Execute a lista de verificação de refatoração antes do RC: Audite os cinco principais arquivos por contagem de linhas e dispersão de importação - módulos "god" bloqueiam PRs paralelos e atualizações de SDK.
Extraia incrementalmente, um limite por PR: Mova um hook ou componente por merge - abandone branches de "limpeza" de várias semanas que divergem de main.
Combine o investimento em arquitetura com o risco: Autenticação, pagamentos e sincronização offline merecem ports e casos de uso - MVPs de três telas merecem hooks e um módulo de API até que a complexidade prove o contrário.
Quando você precisar de IO substituível (mock/staging/prod), testes de unidade de conformidade em regras de negócios, ou múltiplos adaptadores por funcionalidade - não no primeiro dia de um aplicativo CRUD.
Padrão para aplicativos Greenfield. React Navigation brownfield continua suportado - migre quando a dor do deep linking exceder o custo da migração.
Mais do que Query + um store de cliente (Zustand ou Context) justifica uma auditoria. Dados do servidor não devem residir em stores do cliente.
Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (
expo~57.0.4).
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026