Padrões de Codificação e Guias de Estilo

Q: Prettier ou ESLint para ordenação de importações?

Escolha um. Este manual usa Prettier + @ianvs/prettier-plugin-sort-imports. Não ative também as regras de ordem do eslint-plugin-import - elas entram em conflito a cada salvamento.

Q: Avisos na CI - falhar ou permitir?

Falhar em main e release/* com --max-warnings 0. Branches de recursos podem tolerar avisos durante sprints de migração - mas o portão de mesclagem é zero avisos.

Q: Como os guias de estilo se relacionam com expo-rules?

expo-rules são inegociáveis de produto/arquitetura (segredos, OTA, navegação). Guias de estilo são higiene de código. Ambos aparecem no template de PR; violações de expo-rules são sempre bloqueadores.

Um manual para a aplicação do guia de estilo RN/Expo - ESLint, Prettier, TypeScript, revisão de PR e CODEOWNERS configurados para que os padrões sobrevivam à rotatividade sem um xerife de estilo em cada thread.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// package.json - os quatro scripts que cada portão chama
{
  "scripts": {
    "lint": "expo lint",
    "lint:ci": "expo lint -- --max-warnings 0",
    "typecheck": "tsc --noEmit",
    "format:check": "prettier --check .",
    "test": "jest"
  }
}

# Pre-push local (sequência idêntica à CI)
npm run format:check && npm run lint:ci && npm run typecheck && npm run test

Pilha de aplicação
  Prettier     → formatação (aspas, vírgulas, ordem de importação)
  ESLint       → padrões RN/React, hooks, importações restritas
  TypeScript   → tipos rigorosos - sem `any` implícito em src/
  Template de PR  → portões humanos que ESLint não pode cobrir
  CODEOWNERS   → caminhos de configuração de toque nativo e liberação

Quando usar isto:

O tamanho da equipe ultrapassou dois engenheiros e os PRs debatem formatação semanalmente.
Integração de novos contratados de React web que importam hábitos de div para RN.
Você tem Noções Básicas de Padrões escritas, mas ninguém as lê.
CI verde, mas a produção ainda envia any, estilos inline em listas e importações de recursos profundos.
Monorepo precisa dos mesmos portões em apps/mobile e packages/ui.

Quando evitar:

Protótipo solo sem CI - execute npx expo lint e envie; formalize quando um segundo contribuidor se juntar.
Substituir revisão de arquitetura por regras de lint - ESLint não pode impor limites de recursos sem regras personalizadas.

Exemplo de Trabalho

Aplicação de ponta a ponta para um aplicativo Expo SDK 57, desde o scaffold até o PR mesclado.

Passo 1 - Scaffold de lint e formatação

npx create-expo-app@latest StyleApp --template default@sdk-57
cd StyleApp
npx expo lint
npm install --save-dev prettier @ianvs/prettier-plugin-sort-imports eslint-config-prettier

// eslint.config.js - estende a configuração plana do expo
import expo from "eslint-config-expo/flat";
import prettier from "eslint-config-prettier";
 
export default [
  { ignores: [".expo/", "dist/", "ios/", "android/"] },
  ...expo,
  prettier,
  {
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
      "react-hooks/rules-of-hooks": "error",
      "react-hooks/exhaustive-deps": "warn",
    },
  },
];

Configuração completa do ESLint: Noções Básicas de Linting
Ordem de importação: Prettier e Ordenação de Importações

Passo 2 - Linha de base rigorosa do TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
}

npm run typecheck   # deve passar antes de cada mesclagem de PR

Opções mais rigorosas: Modo Rigoroso do TypeScript
tsc e ESLint capturam bugs diferentes - execute ambos em CI

Passo 3 - Husky pre-commit (acelerador opcional)

npm install --save-dev husky
npx husky init

# .husky/pre-commit
npm run format:check && npm run lint && npm run typecheck

Hooks espelham a CI - nunca execute comandos diferentes localmente vs GitHub Actions
Hooks não são um substituto para proteção de branch - desenvolvedores podem usar --no-verify
Portão de CI: Portões de Qualidade de CI

Passo 4 - Regras RN personalizadas para arquitetura

// eslint.config.js - adiciona importações restritas (veja receitas completas na página de regras personalizadas)
{
  rules: {
    "no-restricted-imports": [
      "error",
      {
        patterns: [
          {
            group: ["@/features/*/*"],
            message: "Importe apenas do barril @/features/<nome> - veja CONTRIBUTING.md",
          },
        ],
      },
    ],
  },
}

Proíba StyleSheet.create em caminhos críticos de renderItem de lista via regra personalizada ou checklist de revisão
Proíba console.log em src/ - use um adaptador de logging estruturado
Pacote de regras completo: Regras ESLint Personalizadas para RN

Passo 5 - Fluxo de trabalho de qualidade do GitHub Actions

# .github/workflows/quality.yml
name: Quality Gates
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run format:check
      - run: npm run lint:ci
      - run: npm run typecheck
      - run: npm run test -- --ci

Proteção de branch requer verificação quality - lint vermelho não pode mesclar
Monorepo: turbo run lint typecheck test distribui entre pacotes

Passo 6 - Portões humanos do template de PR

## Estilo e padrões
- [ ] Importações usam apenas barris de recursos (`@/features/<nome>`)
- [ ] Sem novo `any` sem `// eslint-disable-next-line` + comentário de ticket
- [ ] Listas usam FlashList/FlatList - sem ScrollView para feeds dinâmicos
- [ ] Arquivos de toque nativo: diff de pré-compilação anexado (se aplicável)
 
## Evidências
- [ ] Testado em iOS - build_id ou screenshot
- [ ] Testado em Android - build_id ou screenshot

Itens do template referenciam Checklist de Regras do Projeto Expo
Revisores rejeitam "Vou corrigir em um acompanhamento" em violações de padrões - PRs de acompanhamento raramente são mesclados

Passo 7 - CODEOWNERS para configuração e toque nativo

# .github/CODEOWNERS
app.config.ts           @mobile-platform
eas.json                @mobile-release
plugins/                @mobile-platform
ios/                    @mobile-platform
android/                @mobile-platform
.github/workflows/      @mobile-infra

CODEOWNERS solicita automaticamente revisores - complementa ESLint para arquivos que o lint não analisa
Mudanças de configuração de liberação precisam de revisor de Regras de Liberação e OTA

Essenciais do Guia de Estilo

Publique estes itens em docs/STYLE.md - link a partir do template de PR.

TypeScript

Regra	Faça	Não Faça
Props	`type ButtonProps = { label: string }`	props `any`
Componentes	Exportação nomeada ou exportação padrão por arquivo - escolha um por pasta	Padrões mistos
Nulidade	`order?.id` com verificações estritas de nulo	`as` casts para silenciar erros
Enums	Objetos `as const`	`enum` do TypeScript (tree-shaking)

Componentes React / RN

// ✅ Pressable + acessibilidade
<Pressable
  accessibilityRole="button"
  accessibilityLabel="Submit order"
  onPress={onSubmit}
>
  <Text>Submit</Text>
</Pressable>
 
// ❌ TouchableOpacity sem props de a11y em controles interativos

Prefira Pressable em vez de touchables legados para código novo
StyleSheet.create no escopo do módulo - não objetos inline em linhas de lista
Regras de Hooks: Regras de Lint de Hooks do React

Ordem de importação (plugin Prettier)

import { useState } from "react";
import { View, Text } from "react-native";
import { useRouter } from "expo-router";
 
import { Button } from "@/shared/ui";
import { useOrders } from "@/features/orders";
 
import { styles } from "./styles";

Tamanho e complexidade de arquivo

Arquivos de tela visam < 200 linhas - extraia hooks e subcomponentes
Um componente por arquivo a menos que sejam pequenos auxiliares colocados juntos (< 20 linhas)
Complexidade ciclomática: sinalize funções com > 10 branches na revisão - regra opcional do ESLint complexity

Rubrica de Aplicação de Revisão

Severidade	Exemplo	Ação
Bloqueio	Segredo em `EXPO_PUBLIC_*`, importação de recurso profunda, `expo-doctor` ausente em PR de SDK	Solicitar alterações
Bloqueio	`ScrollView` + `.map()` para lista ilimitada	Solicitar alterações
Discutir	Aviso `exhaustive-deps` com exceção documentada	Comentar + ticket
Nit	Renomeação de variável fora do escopo do PR	Aprovar ou acompanhamento opcional

Bloqueadores referenciam um link de documento - não preferência do revisor
Exceções de ADR substituem bloqueadores quando vinculadas - Registros de Decisão de Arquitetura
Escalação: violações repetidas → sessão de programação em par, não chamada pública

Extensão Monorepo

// turbo.json
{
  "pipeline": {
    "lint": { "dependsOn": ["^lint"] },
    "typecheck": { "dependsOn": ["^typecheck"] },
    "test": { "dependsOn": ["^test"] }
  }
}

# package.json raiz
turbo run format:check lint typecheck test

packages/eslint-config compartilhado exporta configuração plana consumida por todos os aplicativos
Uma configuração Prettier na raiz - .prettierignore ignora ios/, android/, .expo/
Verificação de código morto mensalmente: Análise de Código Morto e Dependências

FAQs

Prettier ou ESLint para ordenação de importações?

Escolha um. Este manual usa Prettier + @ianvs/prettier-plugin-sort-imports. Não ative também as regras de ordem do eslint-plugin-import - elas entram em conflito a cada salvamento.

Avisos na CI - falhar ou permitir?

Falhar em main e release/* com --max-warnings 0. Branches de recursos podem tolerar avisos durante sprints de migração - mas o portão de mesclagem é zero avisos.

Como os guias de estilo se relacionam com expo-rules?

expo-rules são inegociáveis de produto/arquitetura (segredos, OTA, navegação). Guias de estilo são higiene de código. Ambos aparecem no template de PR; violações de expo-rules são sempre bloqueadores.

Relacionados

Noções Básicas de Padrões - nomenclatura, pastas, toque nativo
Noções Básicas de Linting - configuração plana do ESLint 9
Portões de Qualidade de CI - configuração do GitHub Actions
Regras ESLint Personalizadas para RN - importações restritas
Checklist de Regras do Projeto Expo - bloqueadores de mesclagem
Melhores Práticas de Linting e Formatação - resumo de 25 pontos
Melhores Práticas de Governança - resumo de governança para toda a equipe

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

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// package.json - os quatro scripts que cada portão chama
{
  "scripts": {
    "lint": "expo lint",
    "lint:ci": "expo lint -- --max-warnings 0",
    "typecheck": "tsc --noEmit",
    "format:check": "prettier --check .",
    "test": "jest"
  }
}

# Pre-push local (sequência idêntica à CI)
npm run format:check && npm run lint:ci && npm run typecheck && npm run test

Pilha de aplicação
  Prettier     → formatação (aspas, vírgulas, ordem de importação)
  ESLint       → padrões RN/React, hooks, importações restritas
  TypeScript   → tipos rigorosos - sem `any` implícito em src/
  Template de PR  → portões humanos que ESLint não pode cobrir
  CODEOWNERS   → caminhos de configuração de toque nativo e liberação

Quando usar isto:

O tamanho da equipe ultrapassou dois engenheiros e os PRs debatem formatação semanalmente.
Integração de novos contratados de React web que importam hábitos de div para RN.
Você tem Noções Básicas de Padrões escritas, mas ninguém as lê.
CI verde, mas a produção ainda envia any, estilos inline em listas e importações de recursos profundos.
Monorepo precisa dos mesmos portões em apps/mobile e packages/ui.

Quando evitar:

Protótipo solo sem CI - execute npx expo lint e envie; formalize quando um segundo contribuidor se juntar.
Substituir revisão de arquitetura por regras de lint - ESLint não pode impor limites de recursos sem regras personalizadas.

Exemplo de Trabalho

Aplicação de ponta a ponta para um aplicativo Expo SDK 57, desde o scaffold até o PR mesclado.

Passo 1 - Scaffold de lint e formatação

npx create-expo-app@latest StyleApp --template default@sdk-57
cd StyleApp
npx expo lint
npm install --save-dev prettier @ianvs/prettier-plugin-sort-imports eslint-config-prettier

// eslint.config.js - estende a configuração plana do expo
import expo from "eslint-config-expo/flat";
import prettier from "eslint-config-prettier";
 
export default [
  { ignores: [".expo/", "dist/", "ios/", "android/"] },
  ...expo,
  prettier,
  {
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
      "react-hooks/rules-of-hooks": "error",
      "react-hooks/exhaustive-deps": "warn",
    },
  },
];

Configuração completa do ESLint: Noções Básicas de Linting
Ordem de importação: Prettier e Ordenação de Importações

Passo 2 - Linha de base rigorosa do TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
}

npm run typecheck   # deve passar antes de cada mesclagem de PR

Opções mais rigorosas: Modo Rigoroso do TypeScript
tsc e ESLint capturam bugs diferentes - execute ambos em CI

Passo 3 - Husky pre-commit (acelerador opcional)

npm install --save-dev husky
npx husky init

# .husky/pre-commit
npm run format:check && npm run lint && npm run typecheck

Hooks espelham a CI - nunca execute comandos diferentes localmente vs GitHub Actions
Hooks não são um substituto para proteção de branch - desenvolvedores podem usar --no-verify
Portão de CI: Portões de Qualidade de CI

Passo 4 - Regras RN personalizadas para arquitetura

// eslint.config.js - adiciona importações restritas (veja receitas completas na página de regras personalizadas)
{
  rules: {
    "no-restricted-imports": [
      "error",
      {
        patterns: [
          {
            group: ["@/features/*/*"],
            message: "Importe apenas do barril @/features/<nome> - veja CONTRIBUTING.md",
          },
        ],
      },
    ],
  },
}

Proíba StyleSheet.create em caminhos críticos de renderItem de lista via regra personalizada ou checklist de revisão
Proíba console.log em src/ - use um adaptador de logging estruturado
Pacote de regras completo: Regras ESLint Personalizadas para RN

Passo 5 - Fluxo de trabalho de qualidade do GitHub Actions

# .github/workflows/quality.yml
name: Quality Gates
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run format:check
      - run: npm run lint:ci
      - run: npm run typecheck
      - run: npm run test -- --ci

Proteção de branch requer verificação quality - lint vermelho não pode mesclar
Monorepo: turbo run lint typecheck test distribui entre pacotes

Passo 6 - Portões humanos do template de PR

## Estilo e padrões
- [ ] Importações usam apenas barris de recursos (`@/features/<nome>`)
- [ ] Sem novo `any` sem `// eslint-disable-next-line` + comentário de ticket
- [ ] Listas usam FlashList/FlatList - sem ScrollView para feeds dinâmicos
- [ ] Arquivos de toque nativo: diff de pré-compilação anexado (se aplicável)
 
## Evidências
- [ ] Testado em iOS - build_id ou screenshot
- [ ] Testado em Android - build_id ou screenshot

Itens do template referenciam Checklist de Regras do Projeto Expo
Revisores rejeitam "Vou corrigir em um acompanhamento" em violações de padrões - PRs de acompanhamento raramente são mesclados

Passo 7 - CODEOWNERS para configuração e toque nativo

# .github/CODEOWNERS
app.config.ts           @mobile-platform
eas.json                @mobile-release
plugins/                @mobile-platform
ios/                    @mobile-platform
android/                @mobile-platform
.github/workflows/      @mobile-infra

CODEOWNERS solicita automaticamente revisores - complementa ESLint para arquivos que o lint não analisa
Mudanças de configuração de liberação precisam de revisor de Regras de Liberação e OTA

Essenciais do Guia de Estilo

Publique estes itens em docs/STYLE.md - link a partir do template de PR.

TypeScript

Regra	Faça	Não Faça
Props	`type ButtonProps = { label: string }`	props `any`
Componentes	Exportação nomeada ou exportação padrão por arquivo - escolha um por pasta	Padrões mistos
Nulidade	`order?.id` com verificações estritas de nulo	`as` casts para silenciar erros
Enums	Objetos `as const`	`enum` do TypeScript (tree-shaking)

Componentes React / RN

// ✅ Pressable + acessibilidade
<Pressable
  accessibilityRole="button"
  accessibilityLabel="Submit order"
  onPress={onSubmit}
>
  <Text>Submit</Text>
</Pressable>
 
// ❌ TouchableOpacity sem props de a11y em controles interativos

Prefira Pressable em vez de touchables legados para código novo
StyleSheet.create no escopo do módulo - não objetos inline em linhas de lista
Regras de Hooks: Regras de Lint de Hooks do React

Ordem de importação (plugin Prettier)

import { useState } from "react";
import { View, Text } from "react-native";
import { useRouter } from "expo-router";
 
import { Button } from "@/shared/ui";
import { useOrders } from "@/features/orders";
 
import { styles } from "./styles";

Tamanho e complexidade de arquivo

Arquivos de tela visam < 200 linhas - extraia hooks e subcomponentes
Um componente por arquivo a menos que sejam pequenos auxiliares colocados juntos (< 20 linhas)
Complexidade ciclomática: sinalize funções com > 10 branches na revisão - regra opcional do ESLint complexity

Rubrica de Aplicação de Revisão

Severidade	Exemplo	Ação
Bloqueio	Segredo em `EXPO_PUBLIC_*`, importação de recurso profunda, `expo-doctor` ausente em PR de SDK	Solicitar alterações
Bloqueio	`ScrollView` + `.map()` para lista ilimitada	Solicitar alterações
Discutir	Aviso `exhaustive-deps` com exceção documentada	Comentar + ticket
Nit	Renomeação de variável fora do escopo do PR	Aprovar ou acompanhamento opcional

Bloqueadores referenciam um link de documento - não preferência do revisor
Exceções de ADR substituem bloqueadores quando vinculadas - Registros de Decisão de Arquitetura
Escalação: violações repetidas → sessão de programação em par, não chamada pública

Extensão Monorepo

// turbo.json
{
  "pipeline": {
    "lint": { "dependsOn": ["^lint"] },
    "typecheck": { "dependsOn": ["^typecheck"] },
    "test": { "dependsOn": ["^test"] }
  }
}

# package.json raiz
turbo run format:check lint typecheck test

packages/eslint-config compartilhado exporta configuração plana consumida por todos os aplicativos
Uma configuração Prettier na raiz - .prettierignore ignora ios/, android/, .expo/
Verificação de código morto mensalmente: Análise de Código Morto e Dependências

FAQs

Prettier ou ESLint para ordenação de importações?

Escolha um. Este manual usa Prettier + @ianvs/prettier-plugin-sort-imports. Não ative também as regras de ordem do eslint-plugin-import - elas entram em conflito a cada salvamento.

Avisos na CI - falhar ou permitir?

Falhar em main e release/* com --max-warnings 0. Branches de recursos podem tolerar avisos durante sprints de migração - mas o portão de mesclagem é zero avisos.

Como os guias de estilo se relacionam com expo-rules?

Relacionados

Noções Básicas de Padrões - nomenclatura, pastas, toque nativo
Noções Básicas de Linting - configuração plana do ESLint 9
Portões de Qualidade de CI - configuração do GitHub Actions
Regras ESLint Personalizadas para RN - importações restritas
Checklist de Regras do Projeto Expo - bloqueadores de mesclagem
Melhores Práticas de Linting e Formatação - resumo de 25 pontos
Melhores Práticas de Governança - resumo de governança para toda a equipe

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

Padrões de Codificação e Guias de Estilo

Buscar na documentação

Padrões de Codificação e Guias de Estilo