Estándares de Codificación y Guías de Estilo

Q: ¿Prettier o ESLint para ordenar imports?

Elige uno. Este cookbook usa Prettier + @ianvs/prettier-plugin-sort-imports. No habilites también reglas de orden de eslint-plugin-import - luchan en cada guardado.

Q: ¿Advertencias en CI - fallar o permitir?

Falla en main y release/* con --max-warnings 0. Las ramas de características pueden tolerar advertencias durante sprints de migración - pero la puerta de fusión es cero advertencias.

Q: ¿Cómo se relacionan las guías de estilo con expo-rules?

expo-rules son innegociables de producto/arquitectura (secretos, OTA, navegación). Las guías de estilo son higiene de código. Ambas aparecen en template de PR; las violaciones de expo-rules siempre son bloqueadores.

Un cookbook para aplicación de guía de estilo RN/Expo - ESLint, Prettier, TypeScript, revisión de PR, y CODEOWNERS conectados para que los estándares sobrevivan a la rotación sin un guardia de estilo en cada hilo.

Receta

Card de receta de referencia rápida - lista para copiar y pegar.

// package.json - los cuatro scripts que cada puerta llama
{
  "scripts": {
    "lint": "expo lint",
    "lint:ci": "expo lint -- --max-warnings 0",
    "typecheck": "tsc --noEmit",
    "format:check": "prettier --check .",
    "test": "jest"
  }
}

# Pre-push local (secuencia idéntica a CI)
npm run format:check && npm run lint:ci && npm run typecheck && npm run test

Stack de aplicación
  Prettier     - formato (comillas, comas, orden de imports)
  ESLint       - patrones RN/React, hooks, imports restringidos
  TypeScript   - tipos strict - sin any implícito en src/
  Template PR  - puertas humanas que ESLint no puede cubrir
  CODEOWNERS   - rutas de configuración native-touch y release

Cuándo usar esto:

El tamaño del equipo cruzó dos ingenieros y los PRs debaten formato semanalmente.
Incorporar contrataciones de React web que importan hábitos de div a RN.
Tienes Standards Basics escrito pero nadie lo lee.
CI verde pero la producción sigue enviando any, estilos en línea en listas, e importaciones profundas de características.
Monorepo necesita las mismas puertas en apps/mobile y packages/ui.

Cuándo evitarlo:

Prototipo solo con sin CI - ejecuta npx expo lint y envía; formaliza cuando un segundo colaborador se une.
Reemplazar revisión de arquitectura con reglas lint - ESLint no puede aplicar límites de características sin reglas personalizadas.

Ejemplo Funcional

Aplicación end-to-end para una app Expo SDK 57 desde scaffold hasta PR fusionado.

Paso 1 - Scaffold de lint y formato

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 - extiende la configuración plana de 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",
    },
  },
];

Configuración completa de ESLint: Linting Basics
Orden de imports: Prettier & Import Sorting

Paso 2 - Línea base TypeScript strict

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

npm run typecheck   # debe pasar antes de cada fusión de PR

Opciones más estrictas: TypeScript Strict Mode
tsc y ESLint detectan bugs diferentes - ejecuta ambos en CI

Paso 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

Los hooks reflejan CI - nunca ejecutes comandos diferentes localmente vs GitHub Actions
Los hooks no son un sustituto de la protección de rama - los desarrolladores pueden --no-verify
Puerta CI: CI Quality Gates

Paso 4 - Reglas personalizadas de RN para arquitectura

// eslint.config.js - añade imports restringidos (ver recetas completas en página de reglas personalizadas)
{
  rules: {
    "no-restricted-imports": [
      "error",
      {
        patterns: [
          {
            group: ["@/features/*/*"],
            message: "Importa desde @/features/<name> barrel solamente - ver CONTRIBUTING.md",
          },
        ],
      },
    ],
  },
}

Prohíbe StyleSheet.create en rutas calientes de list renderItem vía regla personalizada o checklist de revisión
Prohíbe console.log en src/ - usa adaptador de logging estructurado
Pack completo de reglas: Custom ESLint Rules for RN

Paso 5 - Workflow GitHub Actions de calidad

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

Protección de rama requiere chequeo de quality - lint rojo no puede fusionarse
Monorepo: turbo run lint typecheck test expande a través de paquetes

Paso 6 - Puertas humanas del template PR

## Estilo y estándares
- [ ] Los imports usan barrels de características solamente (`@/features/<name>`)
- [ ] Sin nuevo `any` sin `// eslint-disable-next-line` + comentario de ticket
- [ ] Las listas usan FlashList/FlatList - sin ScrollView para feeds dinámicos
- [ ] Archivos native-touch: diff de prebuild adjunto (si aplica)
 
## Evidencia
- [ ] iOS probado - build_id o captura de pantalla
- [ ] Android probado - build_id o captura de pantalla

Los items del template referencian Expo Project Rules Checklist
Los revisores rechazan "Lo arreglaré en un follow-up" en violaciones de estándares - los PRs de follow-up rara vez llegan

Paso 7 - CODEOWNERS para config y native touch

# .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 auto-solicita revisores - complementa ESLint para archivos que lint no puede analizar
Los cambios de configuración de release necesitan revisor de Release and OTA Rules

Esenciales de Guía de Estilo

Publica estos puntos en docs/STYLE.md - enlaza desde el template de PR.

TypeScript

Regla	Haz	No hagas
Props	`type ButtonProps = { label: string }`	props de `any`
Componentes	Named export o default export por archivo - elige uno por carpeta	Patrones mixtos
Nulabilidad	`order?.id` con strict null checks	casts `as` para silenciar errores
Enums	objetos `as const`	TypeScript `enum` (tree-shaking)

Componentes React / RN

// ✅ Pressable + accesibilidad
<Pressable
  accessibilityRole="button"
  accessibilityLabel="Enviar pedido"
  onPress={onSubmit}
>
  <Text>Enviar</Text>
</Pressable>
 
// ❌ TouchableOpacity sin props a11y en controles interactivos

Prefiere Pressable sobre touchables heredados para código nuevo
StyleSheet.create en scope de módulo - no objetos en línea en filas de lista
Reglas de hooks: React Hooks Lint Rules

Orden de imports (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";

Tamaño y complejidad de archivo

Archivos de pantalla objetivo < 200 líneas - extrae hooks y subcomponentes
Un componente por archivo a menos que pequeños helpers colocados (< 20 líneas)
Complejidad ciclomática: marca funciones con > 10 ramas en revisión - regla complexity opcional de ESLint

Rúbrica de Aplicación de Revisión

Severidad	Ejemplo	Acción
Bloquear	Secreto en `EXPO_PUBLIC_*`, importación profunda de características, `expo-doctor` faltante en PR de SDK	Solicita cambios
Bloquear	`ScrollView` + `.map()` para lista sin límites	Solicita cambios
Discutir	Advertencia de `exhaustive-deps` con excepción documentada	Comenta + ticket
Nit	Cambio de nombre de variable fuera del scope de PR	Aprueba o follow-up opcional

Los bloqueadores referencian un enlace de doc - no preferencia del revisor
Las excepciones ADR anulan bloqueadores cuando están enlazadas - Architecture Decision Records
Escalación: violaciones repetidas - sesión de pair programming, no llamada pública

Extensión de Monorepo

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

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

packages/eslint-config compartido exporta configuración plana consumida por todas las apps
Una configuración Prettier en root - .prettierignore salta ios/, android/, .expo/
Escaneo de código muerto mensualmente: Dead Code & Dependency Analysis

Preguntas Frecuentes

¿Prettier o ESLint para ordenar imports?

Elige uno. Este cookbook usa Prettier + @ianvs/prettier-plugin-sort-imports. No habilites también reglas de orden de eslint-plugin-import - luchan en cada guardado.

¿Advertencias en CI - fallar o permitir?

Falla en main y release/* con --max-warnings 0. Las ramas de características pueden tolerar advertencias durante sprints de migración - pero la puerta de fusión es cero advertencias.

¿Cómo se relacionan las guías de estilo con expo-rules?

expo-rules son innegociables de producto/arquitectura (secretos, OTA, navegación). Las guías de estilo son higiene de código. Ambas aparecen en template de PR; las violaciones de expo-rules siempre son bloqueadores.

Relacionado

Standards Basics - naming, folders, native touch
Linting Basics - ESLint 9 flat config
CI Quality Gates - GitHub Actions wiring
Custom ESLint Rules for RN - restricted imports
Expo Project Rules Checklist - merge blockers
Linting & Formatting Best Practices - 25-point summary
Governance Best Practices - team-wide governance summary

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).

Receta

Card de receta de referencia rápida - lista para copiar y pegar.

// package.json - los cuatro scripts que cada puerta llama
{
  "scripts": {
    "lint": "expo lint",
    "lint:ci": "expo lint -- --max-warnings 0",
    "typecheck": "tsc --noEmit",
    "format:check": "prettier --check .",
    "test": "jest"
  }
}

# Pre-push local (secuencia idéntica a CI)
npm run format:check && npm run lint:ci && npm run typecheck && npm run test

Stack de aplicación
  Prettier     - formato (comillas, comas, orden de imports)
  ESLint       - patrones RN/React, hooks, imports restringidos
  TypeScript   - tipos strict - sin any implícito en src/
  Template PR  - puertas humanas que ESLint no puede cubrir
  CODEOWNERS   - rutas de configuración native-touch y release

Cuándo usar esto:

El tamaño del equipo cruzó dos ingenieros y los PRs debaten formato semanalmente.
Incorporar contrataciones de React web que importan hábitos de div a RN.
Tienes Standards Basics escrito pero nadie lo lee.
CI verde pero la producción sigue enviando any, estilos en línea en listas, e importaciones profundas de características.
Monorepo necesita las mismas puertas en apps/mobile y packages/ui.

Cuándo evitarlo:

Prototipo solo con sin CI - ejecuta npx expo lint y envía; formaliza cuando un segundo colaborador se une.
Reemplazar revisión de arquitectura con reglas lint - ESLint no puede aplicar límites de características sin reglas personalizadas.

Ejemplo Funcional

Aplicación end-to-end para una app Expo SDK 57 desde scaffold hasta PR fusionado.

Paso 1 - Scaffold de lint y formato

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 - extiende la configuración plana de 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",
    },
  },
];

Configuración completa de ESLint: Linting Basics
Orden de imports: Prettier & Import Sorting

Paso 2 - Línea base TypeScript strict

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

npm run typecheck   # debe pasar antes de cada fusión de PR

Opciones más estrictas: TypeScript Strict Mode
tsc y ESLint detectan bugs diferentes - ejecuta ambos en CI

Paso 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

Los hooks reflejan CI - nunca ejecutes comandos diferentes localmente vs GitHub Actions
Los hooks no son un sustituto de la protección de rama - los desarrolladores pueden --no-verify
Puerta CI: CI Quality Gates

Paso 4 - Reglas personalizadas de RN para arquitectura

// eslint.config.js - añade imports restringidos (ver recetas completas en página de reglas personalizadas)
{
  rules: {
    "no-restricted-imports": [
      "error",
      {
        patterns: [
          {
            group: ["@/features/*/*"],
            message: "Importa desde @/features/<name> barrel solamente - ver CONTRIBUTING.md",
          },
        ],
      },
    ],
  },
}

Prohíbe StyleSheet.create en rutas calientes de list renderItem vía regla personalizada o checklist de revisión
Prohíbe console.log en src/ - usa adaptador de logging estructurado
Pack completo de reglas: Custom ESLint Rules for RN

Paso 5 - Workflow GitHub Actions de calidad

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

Protección de rama requiere chequeo de quality - lint rojo no puede fusionarse
Monorepo: turbo run lint typecheck test expande a través de paquetes

Paso 6 - Puertas humanas del template PR

## Estilo y estándares
- [ ] Los imports usan barrels de características solamente (`@/features/<name>`)
- [ ] Sin nuevo `any` sin `// eslint-disable-next-line` + comentario de ticket
- [ ] Las listas usan FlashList/FlatList - sin ScrollView para feeds dinámicos
- [ ] Archivos native-touch: diff de prebuild adjunto (si aplica)
 
## Evidencia
- [ ] iOS probado - build_id o captura de pantalla
- [ ] Android probado - build_id o captura de pantalla

Los items del template referencian Expo Project Rules Checklist
Los revisores rechazan "Lo arreglaré en un follow-up" en violaciones de estándares - los PRs de follow-up rara vez llegan

Paso 7 - CODEOWNERS para config y native touch

# .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 auto-solicita revisores - complementa ESLint para archivos que lint no puede analizar
Los cambios de configuración de release necesitan revisor de Release and OTA Rules

Esenciales de Guía de Estilo

Publica estos puntos en docs/STYLE.md - enlaza desde el template de PR.

TypeScript

Regla	Haz	No hagas
Props	`type ButtonProps = { label: string }`	props de `any`
Componentes	Named export o default export por archivo - elige uno por carpeta	Patrones mixtos
Nulabilidad	`order?.id` con strict null checks	casts `as` para silenciar errores
Enums	objetos `as const`	TypeScript `enum` (tree-shaking)

Componentes React / RN

// ✅ Pressable + accesibilidad
<Pressable
  accessibilityRole="button"
  accessibilityLabel="Enviar pedido"
  onPress={onSubmit}
>
  <Text>Enviar</Text>
</Pressable>
 
// ❌ TouchableOpacity sin props a11y en controles interactivos

Prefiere Pressable sobre touchables heredados para código nuevo
StyleSheet.create en scope de módulo - no objetos en línea en filas de lista
Reglas de hooks: React Hooks Lint Rules

Orden de imports (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";

Tamaño y complejidad de archivo

Archivos de pantalla objetivo < 200 líneas - extrae hooks y subcomponentes
Un componente por archivo a menos que pequeños helpers colocados (< 20 líneas)
Complejidad ciclomática: marca funciones con > 10 ramas en revisión - regla complexity opcional de ESLint

Rúbrica de Aplicación de Revisión

Severidad	Ejemplo	Acción
Bloquear	Secreto en `EXPO_PUBLIC_*`, importación profunda de características, `expo-doctor` faltante en PR de SDK	Solicita cambios
Bloquear	`ScrollView` + `.map()` para lista sin límites	Solicita cambios
Discutir	Advertencia de `exhaustive-deps` con excepción documentada	Comenta + ticket
Nit	Cambio de nombre de variable fuera del scope de PR	Aprueba o follow-up opcional

Los bloqueadores referencian un enlace de doc - no preferencia del revisor
Las excepciones ADR anulan bloqueadores cuando están enlazadas - Architecture Decision Records
Escalación: violaciones repetidas - sesión de pair programming, no llamada pública

Extensión de Monorepo

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

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

packages/eslint-config compartido exporta configuración plana consumida por todas las apps
Una configuración Prettier en root - .prettierignore salta ios/, android/, .expo/
Escaneo de código muerto mensualmente: Dead Code & Dependency Analysis

Preguntas Frecuentes

¿Prettier o ESLint para ordenar imports?

Elige uno. Este cookbook usa Prettier + @ianvs/prettier-plugin-sort-imports. No habilites también reglas de orden de eslint-plugin-import - luchan en cada guardado.

¿Advertencias en CI - fallar o permitir?

Falla en main y release/* con --max-warnings 0. Las ramas de características pueden tolerar advertencias durante sprints de migración - pero la puerta de fusión es cero advertencias.

¿Cómo se relacionan las guías de estilo con expo-rules?

Relacionado

Standards Basics - naming, folders, native touch
Linting Basics - ESLint 9 flat config
CI Quality Gates - GitHub Actions wiring
Custom ESLint Rules for RN - restricted imports
Expo Project Rules Checklist - merge blockers
Linting & Formatting Best Practices - 25-point summary
Governance Best Practices - team-wide governance summary

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).

Estándares de Codificación y Guías de Estilo

Buscar en la documentación

Estándares de Codificación y Guías de Estilo