Conceptos básicos de Expo SDK

10 ejemplos para comenzar con paquetes de Expo SDK - 7 básicos e 3 intermedios. Cubre la instalación con npx expo install, versionado del SDK y cómo se inician los módulos nativos dentro de tu aplicación.

Requisitos previos

Crea un aplicación Expo con SDK 57 antes de agregar paquetes SDK:

npx create-expo-app@latest SdkBasics --template blank-typescript
cd SdkBasics

Confirma el pin del SDK:

{
  "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.

Ejemplos básicos

1. Qué son los paquetes de Expo SDK

Los paquetes de Expo SDK son módulos nativos con una API de JavaScript - cámara, sistema de archivos, notificaciones y muchas más se distribuyen como paquetes npm versionados contra una única versión de expo.

import { StatusBar } from "expo-status-bar";
import { StyleSheet, Text, View } from "react-native";
 
export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Paquetes de Expo SDK</Text>
      <Text style={styles.body}>
        Las importaciones de JavaScript llaman código nativo compilado para SDK 57 - no polyfills del navegador.
      </Text>
      <StatusBar style="auto" />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 22, fontWeight: "700" },
  body: { fontSize: 15, color: "#4b5563", lineHeight: 22 },
});

• Cada paquete (expo-camera, expo-location, ...) es un módulo Expo con implementaciones para iOS y Android
• El paquete expo es la raíz del SDK - su versión define qué versiones de módulo son compatibles
• Los paquetes funcionan en Expo Go cuando se enumeran en el cliente Go; el código nativo personalizado requiere una compilación de desarrollo
• Prefiere módulos Expo curados sobre forks de comunidad no mantenidos cuando ambos cubren la misma capacidad

Relacionado: ../expo-platform/expo-platform-basics/expo-platform-basics.md - descripción general de la capa de plataforma | ../expo-platform/expo-modules-core/expo-modules-core.md - bootstrap nativo

2. Instala paquetes con npx expo install

Siempre agrega módulos Expo a través de la CLI para que los rangos de semver coincidan con la matriz de compatibilidad del SDK.

# Uno o más paquetes - versiones resueltas para SDK 57
npx expo install expo-notifications expo-location
 
# Después de ediciones manuales de package.json o un salto de SDK
npx expo install --fix
 
# Verifica que no haya desajuste de versión antes de tu primera compilación nativa
npx expo doctor

{
  "dependencies": {
    "expo": "~57.0.4",
    "expo-notifications": "~0.32.0",
    "expo-location": "~19.0.0"
  }
}

• npx expo install lee tu versión de expo y elige rangos probados - npm install expo-camera@latest puede descargar código nativo incompatible con el SDK
• --fix reconcilia todas las dependencias de Expo después de actualizar expo en package.json
• expo doctor señala copias duplicadas de React Native, versiones de módulo incorrectas y plugins de configuración faltantes
• Confirma package-lock.json / yarn.lock para que CI instale el mismo ABI nativo que tu laptop compiló

Relacionado: ./expo-notifications.md - primera instalación de notificaciones push | ./expo-location.md - permisos de ubicación

3. La versión del SDK como contrato

El campo expo en package.json es la única fuente de verdad que todos los demás paquetes Expo deben satisfacer.

Contrato de SDK 57
 
expo ~57.0.4          ← pin raíz del SDK
├── react 19.2.3      ← emparejado por create-expo-app
├── react-native 0.86.0
├── expo-camera ~17.x ← resuelto por expo install
├── expo-file-system ~19.x
└── …                 ← todos los módulos validados contra la matriz de SDK 57

# Salto intencional del SDK - lee el registro de cambios primero
npx expo install expo@~57.0.4
npx expo install --fix
npx expo prebuild --clean   # cuando existen carpetas nativas

• Mezclar módulos SDK 56 con expo SDK 57 causa errores de compilación nativa - la matriz no es aconsejable
• ~57.0.4 permite lanzamientos de parches dentro de SDK 57 - fija intencionalmente para CI reproducible
• Después de un salto, ejecuta --fix antes de depurar fallos de tiempo de ejecución - el desajuste de versión a menudo surge como excepciones nativas oscuras
• Las carpetas nativas (ios/, android/) deben regenerarse o reconstruirse después de cambios de SDK

Relacionado: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md - guía de actualización

4. Importa y usa un módulo

Los módulos Expo exportan un espacio de nombres o clases nombradas - importa una vez, llama APIs asincrónicas desde efectos o manejadores.

npx expo install expo-haptics

import * as Haptics from "expo-haptics";
import { Pressable, StyleSheet, Text, View } from "react-native";
 
export default function App() {
  return (
    <View style={styles.container}>
      <Pressable
        style={styles.button}
        onPress={() => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)}
      >
        <Text style={styles.label}>Toca para retroalimentación háptica</Text>
      </Pressable>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", alignItems: "center" },
  button: { backgroundColor: "#2563eb", paddingHorizontal: 20, paddingVertical: 12, borderRadius: 10 },
  label: { color: "#fff", fontWeight: "600" },
});

• La mayoría de las APIs son async - los permisos, acceso de hardware y E/S devuelven Promises
• Los tipos de TypeScript se distribuyen con el paquete - no se necesita paquete @types/ para módulos Expo de primer nivel
• Prueba en un dispositivo físico cuando la API toca sensores, push o ejecución de fondo
• Envuelve las llamadas en try/catch - las denegaciones de permisos y la ausencia de hardware lanzan o devuelven errores estructurados

Relacionado: ../rn-fundamentals/platform-specific-code/platform-specific-code.md - guardias Platform.OS

5. Permisos en app.config

Muchos paquetes SDK requieren entradas de manifiesto - decláralas en app.json o app.config.ts antes de solicitar permiso en tiempo de ejecución.

npx expo install expo-camera expo-location

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
export default (): ExpoConfig => ({
  name: "SdkBasics",
  slug: "sdk-basics",
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission:
          "Permite que SdkBasics tome fotos para adjuntos de órdenes de trabajo.",
        microphonePermission:
          "Permite que SdkBasics grabe audio con inspecciones de video.",
      },
    ],
    [
      "expo-location",
      {
        locationAlwaysAndWhenInUsePermission:
          "SdkBasics usa tu ubicación para etiquetar visitas de campo incluso cuando la aplicación está en segundo plano.",
        locationWhenInUsePermission:
          "SdkBasics usa tu ubicación para mostrar sitios de trabajo cercanos.",
      },
    ],
  ],
});

• Las strings de plugin de configuración se convierten en descripciones de uso de iOS Info.plist y justificación de permisos de Android - App Review rechaza copias vagas
• Los plugins se ejecutan en prebuild - cambiarlos requiere un nuevo binario nativo, no solo una actualización OTA de JS
• Solicita permiso en tiempo de ejecución después de explicar el valor en la UI - ver ./best-practices.md
• Empareja la copia del manifiesto con pantallas previas a la solicitud en la aplicación antes de requestPermissionsAsync

Relacionado: ./expo-camera-and-expo-image-picker.md - permisos de captura | ./expo-location.md - strings de divulgación

6. Expo Go vs compilación de desarrollo

Expo Go agrupa un conjunto fijo de módulos nativos. Los paquetes con código nativo personalizado o plugins no publicados necesitan un cliente dev.

npx expo install expo-dev-client
npx expo run:ios
# o cliente dev en la nube:
npx eas build --profile development --platform ios

┌────────────────────┬─────────────────────┬──────────────────────────┐
│ Capacidad          │ Expo Go             │ Compilación de desarrollo│
├────────────────────┼─────────────────────┼──────────────────────────┤
│ expo-notifications │ Configuración de push limitada  │ Push completo + iconos personalizados │
│ expo-camera        │ Sí                 │ Sí + plugins personalizados     │
│ Plugins de configuración     │ Ignorado             │ Aplicado en prebuild      │
│ expo-updates       │ Limitado             │ Canal de OTA de producción   │
└────────────────────┴─────────────────────┴──────────────────────────┘

• Expo Go es más rápido para aprender y trabajar en UI - no para QA final de push, ubicación en segundo plano u OTA
• expo-dev-client reemplaza Go como shell nativo manteniendo Metro con actualización rápida
• Si npx expo start abre Go pero tu característica necesita un plugin, instala dev-client antes de depurar errores nativos 'module not found'
• El envío de tienda siempre usa una compilación EAS o binario de lanzamiento local - nunca Expo Go

Relacionado: ../expo-platform/expo-go-vs-development-builds/expo-go-vs-development-builds.md - matriz de características

7. Ciclo de vida del módulo y entrada de la aplicación

Algunos módulos requieren registro antes de que React se monte - las tareas de fondo, manejadores de notificaciones y listeners de actualización pertenecen al ámbito global.

npx expo install expo-notifications expo-task-manager

// index.ts - importaciones de efectos secundarios ANTES de registerRootComponent
import "./src/notifications/notificationHandler";
import "./src/background/locationTask";
import { registerRootComponent } from "expo";
import App from "./App";
 
registerRootComponent(App);

// src/notifications/notificationHandler.ts
import * as Notifications from "expo-notifications";
 
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

• TaskManager.defineTask debe ejecutarse en el ámbito global - definirlo dentro de un componente falla en el inicio en frío del SO
• Los manejadores de notificaciones se configuran antes de que llegue la primera notificación - importa el módulo al entrar
• Las aplicaciones Expo Router usan app/_layout.tsx importaciones de nivel superior para los mismos efectos secundarios
• Mantén los efectos secundarios de entrada pequeños - el trabajo pesado todavía pertenece a módulos cargados perezosamente

Relacionado: ./expo-task-manager-and-background-tasks.md - registro de tareas globales | ./expo-notifications.md - manejador de primer plano

Ejemplos intermedios

8. Autolinking y generación de proyectos nativos

Expo autolinking descubre módulos nativos de package.json y los conecta a proyectos ios/ y android/ generados.

npx expo prebuild
# inspecciona proyectos nativos sin abrir Xcode
ls ios/Pods 2>/dev/null || ls android/app/build.gradle

{
  "expo": {
    "plugins": ["expo-notifications"]
  }
}

• npx expo prebuild genera carpetas nativas de app.config + módulos instalados - CNG las mantiene fuera de git en el flujo de trabajo administrado
• Autolinking lee expo-module.config.json en cada paquete - las ediciones manuales de pod install se sobrescriben en el próximo prebuild
• Agregar un paquete con un plugin de configuración cambia los proyectos nativos - confirma la configuración, no Info.plist editado a mano, cuando uses CNG
• Los equipos de flujo de trabajo sin procesar aún ejecutan npx expo install para seguridad de versiones - autolinking funciona de la misma manera

Relacionado: ../cng-prebuild/prebuild-basics/prebuild-basics.md - cuándo hacer prebuild | ../native-modules/native-modules-basics/native-modules-basics.md - arquitectura de módulos

9. APIs heredadas vs modernas dentro de un paquete

Algunos paquetes SDK se distribuyen tanto con una API moderna como con una entrada /legacy - migra deliberadamente, no en un PR.

npx expo install expo-file-system

// API moderna de SDK 57 - File, Directory, Paths
import { Directory, File, Paths } from "expo-file-system";
 
const cacheDir = new Directory(Paths.cache, "downloads");
cacheDir.create();
const meta = new File(cacheDir, "manifest.json");
meta.create();
meta.write(JSON.stringify({ version: 1 }));
 
// API heredada - todavía disponible durante la migración
import * as FileSystem from "expo-file-system/legacy";
 
const legacyUri = meta.uri;
const text = await FileSystem.readAsStringAsync(legacyUri);

• Prefiere File / Directory / Paths para código nuevo en SDK 57 - las rutas orientadas a objetos reducen bugs de cadenas URI
• Importa expo-file-system/legacy solo para sitios de llamadas no migrados - planifica la eliminación por versión
• Lee el registro de cambios de cada paquete en un salto de SDK - los cambios de nombre y deprecaciones son por módulo, no solo en las notas de lanzamiento de expo
• Ver ./expo-file-system.md para rutas de sandbox y patrones de descarga

Relacionado: ./expo-file-system.md - rutas en sandbox y descargas

10. Comportamiento de paquete específico del entorno

Usa app.config.ts y entornos EAS para variar permisos, plugins y claves API - no forks if (__DEV__) en rutas de producción.

// app.config.ts
const IS_DEV = process.env.APP_VARIANT === "development";
 
export default {
  name: IS_DEV ? "SdkBasics (Dev)" : "SdkBasics",
  slug: "sdk-basics",
  extra: {
    eas: { projectId: process.env.EAS_PROJECT_ID },
    pushEnabled: !IS_DEV,
  },
  plugins: [
    ...(IS_DEV ? [] : [["expo-notifications", { icon: "./assets/notification-icon.png" }]]),
  ],
};

import Constants from "expo-constants";
 
const pushEnabled = Constants.expoConfig?.extra?.pushEnabled ?? false;

• extra está disponible en tiempo de ejecución a través de expo-constants - adecuado para banderas de características resueltas en tiempo de compilación
• EXPO_PUBLIC_* se inserta en JS - nunca pongas secretos allí; solo URLs de API cuando sea intencionalmente público
• Desactiva plugins de push en dev cuando pruebes sin credenciales de APNs/FCM - reduce la fricción de configuración nativa
• Alinea variantes con ../expo-platform/environments-and-eas-environment-variables/environments-and-eas-environment-variables.md

Relacionado: ../expo-platform/app-json-and-app-config-js/app-json-and-app-config-js.md - configuración dinámica

Preguntas frecuentes

npx expo install expo-camera
npx expo doctor

Relacionado

• expo-notifications - notificaciones push y locales
• expo-location - ubicación de primer plano y fondo
• expo-file-system - almacenamiento del dispositivo
• expo-secure-store & expo-crypto - secretos y hash
• ../expo-platform/expo-platform-basics/expo-platform-basics.md - fundamentos de plataforma
• Expo SDK Packages Best Practices - resumen de la sección

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