Padrões React Native / Expo

Padrões práticos para construir aplicativos React Native de produção com Expo. Abrange navegação, estado, busca de dados, listas, estilização e APIs nativas. Complementa o conjunto de regras rules/react-native/: as regras dizem o quê impor, esta habilidade mostra como.

As bibliotecas nomeadas abaixo (NativeWind, Zustand/Jotai, TanStack Query) são opções comuns e bem estabelecidas mostradas para ilustração — os padrões importam mais do que o pacote específico, e qualquer equivalente funciona. Zod é usado para validação para manter a consistência com as regras existentes de typescript/ da ECC.

Esses padrões assumem o fluxo gerenciado do Expo (Expo Router, EAS, módulos expo-*) na Nova Arquitetura (o padrão nos SDKs recentes do Expo, obrigatório a partir do SDK 55+). Eles NÃO assumem o DOM do navegador — React Native não tem <div>, barra de URL, nem padrões de busca de dados da web.

Quando Ativar

Use esta habilidade quando:

• Construindo ou editando telas, componentes ou navegação React Native / Expo
• Configurando roteamento com Expo Router (roteamento baseado em arquivo na pasta app/)
• Decidindo onde o estado pertence (cache do servidor vs. armazenamento do cliente vs. parâmetros de rota vs. formulário)
• Conectando a busca de dados com TanStack Query e validando respostas com Zod
• Renderizando listas longas ou pesadas
• Escolhendo ou aplicando uma abordagem de estilização (NativeWind ou StyleSheet)
• Acessando APIs nativas do dispositivo (câmera, localização, notificações) ou armazenamento seguro
• Revisando código RN para problemas específicos de mobile

NÃO use os padrões web/React-DOM aqui — URL-como-estado, <div> e SWR-para-navegador não se aplicam ao React Native.

Conceitos Principais

Estrutura do projeto (Expo Router)

Roteamento baseado em arquivo sob app/. Mantenha os arquivos de rota enxutos: eles leem e validam parâmetros, depois delegam para um componente de tela que vive em components/ ou features/.

app/
  _layout.tsx          # root stack
  (tabs)/
    _layout.tsx        # tab navigator
    index.tsx          # Home
  user/[id].tsx        # dynamic route
components/
features/
  user/UserProfile.tsx

Navegação: valide parâmetros de rota

Deep links e rotas dinâmicas entregam strings não confiáveis. Valide-as com Zod antes de usar.

// app/user/[id].tsx
import { useLocalSearchParams, router } from 'expo-router'
import { z } from 'zod'
import { UserProfile } from '@/features/user/UserProfile'

const Params = z.object({ id: z.string().uuid() })

export default function UserRoute() {
  const parsed = Params.safeParse(useLocalSearchParams())
  if (!parsed.success) {
    router.replace('/not-found')
    return null
  }
  return <UserProfile userId={parsed.data.id} />
}

Estado: mantenha as preocupações separadas

Não duplique dados do servidor em um armazenamento do cliente. Cada preocupação tem seu próprio lugar.

Prefira useState local até que o estado realmente precise ser compartilhado.

Busca de dados: uma biblioteca de cache + Zod

Use uma biblioteca de cache do servidor (TanStack Query, SWR) em vez de fetch-in-useEffect. Valide na fronteira e infira tipos do schema. Lide explicitamente com estados de carregamento, erro e vazio. (O exemplo usa TanStack Query.)

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { z } from 'zod'

const User = z.object({ id: z.string(), email: z.string().email() })
type User = z.infer<typeof User>

export function useUser(id: string) {
  return useQuery({
    queryKey: ['user', id],
    queryFn: async (): Promise<User> => User.parse(await api.getUser(id)),
  })
}

export function useUpdateEmail(id: string) {
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (email: string) => api.updateEmail(id, email),
    onSuccess: () => qc.invalidateQueries({ queryKey: ['user', id] }),
  })
}

Listas: virtualize, nunca mapeie um array grande em um ScrollView

import { FlatList } from 'react-native'

<FlatList
  data={items}
  keyExtractor={(item) => item.id}
  renderItem={renderItem}          // memoized
  initialNumToRender={10}
  windowSize={5}
/>

Use FlashList (Shopify) para listas grandes ou heterogêneas.

Estilização: escolha um sistema

…