Conceptos básicos de incorporación

10 ejemplos para setup de máquina del primer día - Xcode, Android Studio, EAS CLI, simuladores, y pin de SDK 57 - para que un nuevo compañero de equipo ejecute la aplicación antes del almuerzo.

Requisitos previos

Clona el repo del equipo y confirma el contrato SDK en package.json antes de instalar herramientas nativas. Si el proyecto usa la plantilla predeterminada, espera Expo Router y flujo de trabajo administrado (sin ios/ / android/ comprometidos hasta prebuild o EAS).

git clone git@github.com:your-org/your-app.git
cd your-app
node -v   # espera 20.x
cat package.json | grep '"expo"'

Stack de destino para esta sección:

{
  "engines": { "node": ">=20.0.0" },
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Herramientas: Estos ejemplos apuntan a Expo SDK 57 (expo ~57.0.4), React Native 0.86.0, y React 19.2.3. Consulta Conceptos básicos de configuración del proyecto para flags de scaffold y diseño de carpetas.

Ejemplos básicos

1. Node 20 y Gestor de paquetes

Instala Node 20 LTS con nvm, fnm, o mise - las herramientas SDK 57 y EAS CLI lo esperan.

# ejemplo de nvm
nvm install 20
nvm use 20
node -v   # v20.x.x
 
npm install
# o: corepack enable && pnpm install

{
  "engines": {
    "node": ">=20.0.0"
  }
}

• Un lockfile en el repo - usa el mismo gestor de paquetes que el equipo documenta en CONTRIBUTING.md
• npm ci en CI; localmente npm install está bien después del clone
• Si engines falla, corrige Node antes de perseguir errores de Metro - Node incorrecto causa fallos criptográficos de transform

Relacionado: Conceptos básicos de configuración del proyecto - higiene de lockfile y .gitignore

2. Verificación del pin de SDK 57

La versión del paquete expo es el contrato de compatibilidad para cada módulo expo-*.

npm install
npx expo-doctor
npx expo install --check

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

• npx expo-doctor compara tu gráfico con la matriz SDK 57 - ejecuta en el primer día y después de cada git pull
• npx expo install <pkg> resuelve versiones de peers - nunca elijas manualmente expo-camera sin él
• Síntoma de falta de coincidencia: pantalla roja mencionando versión de módulo nativo o errores de análisis de Hermes
• Los nuevos miembros no deben bumpar SDK en la primera semana a menos que se les asigne - fija primero, actualiza después

Relacionado: Plantillas create-expo-app - scaffold default@sdk-57

3. Variables de entorno y secretos

Copia el archivo de entorno de ejemplo antes de la primera ejecución - las URLs de API faltantes causan pantallas en blanco silenciosas.

cp .env.example .env.local

# .env.example (comprometido)
EXPO_PUBLIC_API_URL=https://api.staging.example.com
# secretos de EAS - no en .env para construcciones de producción

// app.config.ts - superficie vars públicas vía extra cuando sea necesario
export default {
  expo: {
    extra: {
      apiUrl: process.env.EXPO_PUBLIC_API_URL,
    },
  },
};

• EXPO_PUBLIC_* vars incrusta en el bundle de JS - nunca pongas claves privadas aquí
• Los secretos de producción viven en EAS Environment Variables, no en archivos .env de laptop
• Pide a tu líder enlaces de 1Password / vault a EXPO_TOKEN, cuentas de staging, e invitaciones de TestFlight
• Reinicia Metro después de cambiar vars de entorno: npx expo start -c

4. Primera ejecución - Metro y Expo Go

Confirma que JavaScript se inicia antes de instalar IDEs nativas de varios gigabytes.

npx expo start
# presiona i para simulador de iOS (requiere Xcode)
# presiona a para emulador de Android (requiere Android Studio)
# escanea QR con Expo Go en un dispositivo físico

{
  "scripts": {
    "start": "expo start",
    "ios": "expo start --ios",
    "android": "expo start --android"
  }
}

• Expo Go es más rápido para trabajo de Router y UI - módulos nativos limitados
• expo start -c limpia el caché de Metro cuando las importaciones se ven obsoletas después de cambios de rama
• Si el proyecto usa expo-dev-client, el primer día puede requerir una construcción de desarrollo - verifica eas.json para el perfil development
• Criterios de éxito: pantalla de inicio se carga, sin redbox, tsc --noEmit pasa

Relacionado: Conceptos básicos de Expo Router - rutas basadas en archivos en app/

5. Xcode e iOS Simulator (macOS)

El desarrollo de iOS requiere Xcode desde la Mac App Store y herramientas de línea de comandos.

xcode-select --install
sudo xcodebuild -license accept
xcode-select -p
# /Applications/Xcode.app/Contents/Developer
 
# Listar simuladores
xcrun simctl list devices available
 
# Abrir app Simulator
open -a Simulator

npx expo start --ios
# o: npx expo run:ios

• Instala Xcode 16+ compatible con SDK 57 - coincide con lo que CI/EAS usa cuando está documentado
• El primer run:ios puede desencadenar CocoaPods (pod install) si ios/ existe o después del prebuild
• Apple Silicon: los simuladores son arm64 - más rápido que imágenes x86 de Rosetta
• Compañeros de Windows/Linux usan EAS Build para artefactos de iOS - no se requiere compilación local

6. Android Studio y Emulador

Las construcciones de Android necesitan Android Studio con SDK Platform 35 y un dispositivo virtual (AVD).

# Después de la instalación de Android Studio - establecer ANDROID_HOME
export ANDROID_HOME=$HOME/Library/Android/sdk   # macOS
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
 
adb devices
emulator -list-avds

Android Studio → SDK Manager:

• SDK Platforms: Android 15 (API 35) - coincide con los predeterminados de RN 0.86
• SDK Tools: Android SDK Build-Tools, Platform-Tools, Emulator

npx expo start --android

• Crea un AVD con imagen Google Play al probar características de Play Services
• adb reverse ayuda a Metro a alcanzar APIs localhost: adb reverse tcp:8081 tcp:8081
• Habilita USB debugging en dispositivos Android físicos para dev en dispositivo

7. EAS CLI y Cuenta Expo

EAS CLI conecta tu máquina al servicio de construcción en la nube de Expo - requerido para binarios con forma de tienda.

npm install -g eas-cli@latest
# o local del proyecto: npx eas-cli@latest
 
eas login
eas whoami
 
cd your-app
eas build:configure   # crea eas.json si falta

// eas.json (inicial mínimo)
{
  "cli": { "version": ">= 16.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal"
    },
    "production": {}
  }
}

• eas login usa tu cuenta Expo - solicita invitación de org al líder de móviles
• eas build:configure vincula el ID del proyecto en app.config.ts vía extra.eas.projectId
• CI usa cuenta de robot EXPO_TOKEN - los humanos usan eas login; nunca commits tokens
• Primera construcción en la nube: eas build --profile development --platform ios --local opcional; el predeterminado es en la nube

Relacionado: Conceptos básicos de EAS Build - perfiles, credenciales, primera construcción

Ejemplos intermedios

8. Cliente de desarrollo vs Expo Go

Cuando la aplicación agrega módulos nativos personalizados o plugins de configuración, Expo Go no es suficiente - instala un cliente dev.

npx expo install expo-dev-client
eas build --profile development --platform ios
# Instala IPA desde QR del dashboard de EAS
npx expo start --dev-client

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": { "simulator": true }
    }
  }
}

• Perfil de desarrollo incluye expo-dev-client y código nativo de plugins de configuración
• Construcciones de simulador (ios.simulator: true) se instalan más rápido para trabajo UI solo de iOS
• Reconstruye cliente dev cuando cambien deps nativos - cambios solo de JS aún con hot-reload
• Documenta qué perfil los nuevos miembros deben instalar en el documento de incorporación

Relacionado: Conceptos básicos de EAS Build - developmentClient: true

9. Atajos de simulador y emulador

Estandariza nombres de dispositivos para que sesiones de pairing y capturas de pantalla coincidan.

# iOS - arrancar simulador nombrado
xcrun simctl boot "iPhone 16"
open -a Simulator
 
# Android - iniciar AVD por nombre
emulator -avd Pixel_8_API_35 &
 
# Expo apunta a dispositivo específico
npx expo run:ios --device "iPhone 16"
npx expo run:android --device Pixel_8_API_35

// package.json - atajos del equipo (opcional)
{
  "scripts": {
    "ios:16": "expo run:ios --device 'iPhone 16'",
    "android:pixel": "expo run:android --device Pixel_8_API_35"
  }
}

• Misma clase de dispositivo en revisiones de diseño - evita sorpresas de "funciona en mi iPhone SE"
• Restablece simuladores cuando el Keychain o el estado de push se corrompen: xcrun simctl erase all (destructivo)
• Dispositivos físicos: registra UDIDs para distribución interna de iOS en credenciales de EAS

10. Lista de verificación de verificación del primer día

Ejecuta este bloque de script antes de abrir tu primer PR - detecta el 90% de sesgos de incorporación.

node -v                    # 20.x
npm ci
npx expo-doctor
npm run typecheck          # o: npx tsc --noEmit
npm run lint
npm test -- --passWithNoTests
npx expo start

## Fragmento de CONTRIBUTING.md - Setup de máquina
1. Node 20 vía nvm
2. Clone + `npm ci`
3. `cp .env.example .env.local` (pide valores a #mobile)
4. `npx expo-doctor` - debe pasar
5. `npx expo start` - smoke test de simulador de iOS + emulador de Android
6. `eas login` + invitación de org
7. Instala cliente dev desde el perfil `development` de EAS si el repo tiene expo-dev-client

• Agrega npx expo customize tsconfig.json si las rutas tipadas fallan en un clone limpio
• Captura de pantalla pasando expo-doctor en tu PR de incorporación si tu equipo rastrea listas de verificación de contratación
• Escala al canal de plataforma cuando doctor falla en clone fresco - probable sesgos del repo, no error de incorporación

Relacionado: Mejores prácticas de configuración del proyecto - convenciones que sobreviven la segunda semana

FAQs

Relacionado

• Conceptos básicos de configuración del proyecto - scaffold, pin de SDK, diseño de carpetas
• Conceptos básicos de EAS Build - primera construcción en la nube
• Conceptos básicos de Expo Router - modelo mental de app/
• Ruta de aprendizaje de la primera semana - qué aprender después del setup de máquina
• Lista de verificación de gira de codebase - dónde vive el código

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