Noções Básicas de Padrões

10 exemplos de convenções de equipe além do ESLint - nomenclatura, pastas e regras de toque nativo que sobrevivem a mudanças de SDK e a novos contratados. Sete básicos e três intermediários.

Pré-requisitos

Comece com um projeto Expo SDK 57 com TypeScript e Expo Router. Os padrões vivem em docs/CONTRIBUTING.md (ou docs/standards.md) e são aplicados na revisão de PR - não apenas no chat.

npx create-expo-app@latest MyApp --template default@sdk-57
cd MyApp
npx expo lint

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Ferramentas: Estes exemplos visam Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. A configuração do ESLint está em Noções Básicas de Linting; as regras do projeto estão em Checklist de Regras do Projeto Expo.

Exemplos Básicos

1. Tabela de Convenções de Nomenclatura

Publique uma tabela - debata uma vez, referencie para sempre.

// src/features/order-history/components/OrderSummaryCard.tsx
export function OrderSummaryCard({ orderId }: { orderId: string }) {
  return null;
}

• Nome do arquivo corresponde à exportação padrão para componentes - grep e jump-to-definition do IDE permanecem previsíveis
• Hooks vivem em hooks/ dentro da feature ou em src/shared/hooks/ quando entre features
• Nomes de parâmetros de rota no Expo Router usam camelCase no código (orderId) mesmo quando o segmento da URL é kebab-case

Relacionado: Prettier & Ordenação de Importações - formatação não é nomenclatura | Padrões de Código e Guias de Estilo - manual de aplicação

2. Layout de Pastas - Expo Greenfield

Alinhe com Noções Básicas de Arquitetura Mobile: app/ fina, src/features/ gorda.

MyApp/
├── app/                          # apenas rotas - sem lógica de negócio
│   ├── (tabs)/
│   │   ├── index.tsx
│   │   └── orders/
│   │       └── [id].tsx
│   └── _layout.tsx
├── src/
│   ├── shared/                   # api, primitivos de ui, helpers de configuração
│   ├── entities/                 # User, Order - substantivos do domínio
│   └── features/
│       ├── auth/
│       │   ├── index.ts          # api pública
│       │   ├── screens/
│       │   ├── components/
│       │   ├── hooks/
│       │   └── model/
│       └── orders/
├── plugins/                      # plugins de configuração - zona de toque nativo
├── app.config.ts
├── eas.json
└── docs/
    ├── CONTRIBUTING.md           # padrões vivem aqui
    └── adr/

• Arquivos app/ devem reexportar telas de features - uma linha quando possível
• src/features/<nome>/index.ts é o único caminho de importação que outros módulos usam
• Alterações em plugins/ e app.config.ts disparam revisão nativa - veja regras de toque nativo abaixo
• Não crie uma gaveta de lixo src/utils/ - promova para shared/ com um propósito nomeado

Relacionado: Checklist de Regras do Projeto Expo - Regras de pasta Nível 2

3. API Pública de Feature - Sem Importações Profundas

// ✅ Correto - o consumidor importa do barrel da feature
import { OrdersScreen, type Order } from "@/features/orders";
 
// ❌ Errado - acopla a refatoração interna
import { OrderRow } from "@/features/orders/components/OrderRow";

// src/features/orders/index.ts
export { OrdersScreen } from "./screens/OrdersScreen";
export type { Order } from "./model/types";
// Não exporte OrderRow a menos que outra feature realmente precise dela

• Exportações de barrel são intencionais - componentes internos permanecem privados até que uma segunda feature os necessite
• ESLint no-restricted-imports pode impor caminhos @/features/*/* - veja Regras Personalizadas do ESLint para RN
• Quando duas features compartilham UI, mova o componente para src/shared/ui/ - não exporte internos irmãos

4. Disciplina de Arquivo de Rota

// app/(tabs)/orders/index.tsx
export { OrdersScreen as default } from "@/features/orders";

// app/orders/[id].tsx - o parsing de parâmetros permanece na camada de rota
import { useLocalSearchParams } from "expo-router";
import { OrderDetailScreen } from "@/features/orders";
 
export default function OrderDetailRoute() {
  const { id } = useLocalSearchParams<{ id: string }>();
  if (!id) return null;
  return <OrderDetailScreen orderId={id} />;
}

• Analise os parâmetros uma vez no arquivo de rota; passe props tipadas para a tela
• Layouts (_layout.tsx) possuem provedores e configuração de stack/tab - não regras de negócio de feature
• Rotas modais seguem Regras de Navegação e Roteamento - um padrão de apresentação por aplicativo

5. Regras de Toque Nativo - Quem Pode Editar O Quê

# Após mudança de plugin ou SDK - obrigatório em equipes CNG
npx expo prebuild --clean
git diff ios/ android/

• Equipes CNG ignoram pastas nativas no git - editar manualmente Info.plist garante a sobrescrita pelo EAS
• Repositórios host Brownfield seguem Noções Básicas de Brownfield - atualizações de versão de artefatos, não bundles copiados e colados
• Qualquer exceção precisa de um ADR em docs/adr/ - "temporário" sem ADR se torna anos de desvio

Relacionado: Regras de Módulos Nativos - quando JS não é suficiente

6. Nomenclatura de Branch e Ticket

feat/SHIP-412-order-summary-sheet
fix/SHIP-419-crash-on-logout
chore/upgrade-expo-sdk-57
spike/expo-ui-tab-bar
release/2.6.0
hotfix/2.5.1

• Prefixo corresponde ao tipo de commit convencional - feat, fix, chore, spike
• ID do ticket exigido quando sua organização usa Jira/Linear - cherry-picks dependem de rastreabilidade
• spike/* nunca faz merge em main sem resultado de ADR - veja Spikes, PoCs e Nova Arquitetura
• Atualizações de SDK usam branches dedicados chore/upgrade-* - não misturados com trabalho de feature

Relacionado: Noções Básicas de Git para Equipes Mobile

7. Nomenclatura de Ambiente e Segredos

Ambiente EAS:     development | preview | production
Arquivos .env:    .env.local (gitignored), .env.example (commitado)
Variáveis públicas em tempo de execução: Apenas EXPO_PUBLIC_* - nunca segredos
Configuração:     app.config.ts lê process.env no tempo de build

// app.config.ts - padrão
const IS_DEV = process.env.APP_ENV === "development";
 
export default {
  expo: {
    extra: {
      apiUrl: process.env.EXPO_PUBLIC_API_URL,
    },
  },
};

• EXPO_PUBLIC_* são embutidos no tempo de bundle - trate como visíveis para usuários; veja Regras de Segurança para Mobile
• .env.example documenta cada chave necessária com valores de placeholder - o onboarding copia para .env.local
• Nomes de perfil em eas.json correspondem a development / preview / production - sem staging2

Exemplos Intermediários

8. Nomenclatura de Pacotes Monorepo

apps/
  mobile/                 # App Expo - consumidor principal
packages/
  ui/                     # @myorg/ui - componentes RN compartilhados
  api-client/             # @myorg/api-client - camada de fetch
  tsconfig/               # @myorg/tsconfig - bases compartilhadas

{
  "name": "@myorg/ui",
  "main": "src/index.ts",
  "peerDependencies": {
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

• Um único lockfile na raiz do repositório - apps não flutuam árvores independentes
• Pacotes expõem src/index.ts - mesma regra de barrel que features
• Dependências de pares fixam RN/React - o pacote do workspace não deve empacotar React duplicado
• Pipeline Turbo executa os mesmos scripts lint / typecheck - Portões de Qualidade de CI

9. Padrões de Módulo Nativo e Plugin de Configuração

Ao adicionar um plugin de configuração ou módulo nativo personalizado:

plugins/
  withMySdk.ts            # plugin de configuração
src/modules/
  my-sdk/                 # módulo Expo local opcional
    expo-module.config.json
    ios/
    android/

# Checklist de PR para PRs de toque nativo
npx expo prebuild --clean
npx expo-doctor
eas build --profile preview --platform all

• ID do plugin corresponde ao nome do pacote npm ou função with* - um plugin por arquivo
• Documente as permissões iOS/Android adicionadas no template de PR - a revisão de loja lê essas strings
• Compatibilidade com Nova Arquitetura anotada em ADR - RN 0.86 usa NA por padrão em greenfield
• Siga Regras de Módulos Nativos antes de expo prebuild

10. Template de Documento de Padrões

Commit docs/CONTRIBUTING.md com marcadores aplicáveis - link a partir do template de PR.

# Padrões Mobile (SDK 57)
 
## Nomenclatura
- Componentes: Arquivos PascalCase correspondendo à exportação
- Rotas: Pastas kebab-case sob app/
 
## Importações
- Features: importar apenas de @/features/<nome>
- Sem exportações padrão em hooks/utils - apenas exportações nomeadas
 
## Toque Nativo
- Sem edições manuais de ios/ android/ sob CNG
- Mudanças em plugins/ exigem diff de prebuild --clean no PR
 
## Revisão
- PRs de UI: Screenshot iOS + Android ou build_id
- PRs de Toque Nativo: Revisor de plataforma exigido
 
## Exceções
- Registrar em docs/adr/NNNN-titulo.md - link no PR

• Revisar trimestralmente e após cada atualização de SDK - Rastreamento de Depreciação e Fim de Vida
• Checkbox no template de PR - "Eu li CONTRIBUTING.md" vence lembretes do Slack
• Dia um de onboarding - atribuir a leitura de Melhores Práticas das Regras Expo + este documento

FAQs

Relacionado

• Padrões de Código e Guias de Estilo - aplicação de lint + revisão
• Checklist de Regras do Projeto Expo - 25 itens inegociáveis
• Noções Básicas de Linting - configuração plana ESLint 9
• Noções Básicas de Arquitetura Mobile - limites de camada
• Regras de Módulos Nativos - governança de mudanças nativas
• Melhores Práticas de Governança - resumo condensado de 25 pontos

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).