Referencia: Aplicación B2C Expo SaaS

Una arquitectura de referencia compuesta para un cliente móvil B2C subscription SaaS - colaboración en equipo, seguimiento de hábitos o CRM ligero. La stack está fijada a Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 y React 19.2.3. No es un producto enviado; destila patrones que recorren aplicaciones SaaS de producción en EAS.

Contexto

Limitaciones al inicio:

• Entregar iOS y Android desde una base de código TypeScript única con cadencia semanal de lanzamientos JS y mensual de nativos.
• Marketing necesita enlaces universales a contenido paywall; las notificaciones push deben abrir la pantalla correcta.
• Backend es REST + WebSocket; sin cola de mutación offline en v1 - las lecturas deben sobrevivir caídas breves del túnel.
• Equipo de seis ingenieros; sin equipo nativo dedicado; CI publica a través de EAS Build y EAS Update.

No-objetivos para v1: Pinning de certificados, sabores white-label multi-tenant, incrustación nativa brownfield.

Arquitectura

┌─────────────────────────────────────────────────────────────────────────┐
│                    B2C SaaS - capas lógicas                             │
├─────────────────────────────────────────────────────────────────────────┤
│  app/ (Expo Router)                                                      │
│    (auth)/sign-in, sign-up          ← grupo de rutas sin autenticar     │
│    (app)/(tabs)/home|inbox|settings ← shell autenticado                 │
│    (app)/paywall/[sku]              ← presentación modal                 │
├─────────────────────────────────────────────────────────────────────────┤
│  src/features/*                     ← pantallas, hooks, APIs de features│
│  src/api/client.ts                  ← envolvente fetch + encabezado auth│
├─────────────────────────────────────────────────────────────────────────┤
│  TanStack Query (estado del servidor)← caché, staleTime, mutaciones     │
│  MMKV (prefs, flags)                ← tema, última pestaña, alternancias│
├─────────────────────────────────────────────────────────────────────────┤
│  expo-secure-store                  ← solo token de actualización        │
├─────────────────────────────────────────────────────────────────────────┤
│  EAS Build (binarios)               development | preview | production   │
│  EAS Update (JS OTA)                canal por perfil, runtimeVersion    │
└─────────────────────────────────────────────────────────────────────────┘

Ruta de solicitud (lectura autenticada):

Montaje de pantalla → useQuery(key) → ¿Impacto de caché Query?
  ├─ sí + fresco → renderizar
  ├─ sí + obsoleto → renderizar + refetch de fondo
  └─ no → client.ts fetch → API → escritura de caché → renderizar

Ruta de lanzamiento:

Etiqueta Git v2.4.0 → eas build --profile production → envío a store
       │
       └─ mismo runtime → eas update --channel production (corrección de JS)

El inicio en frío carga la raíz _layout.tsx, que lee la sesión desde SecureStore, hidrata Query queryClient y redirige entre grupos (auth) y (app). Los archivos de ruta se mantienen finos - re-exportan pantallas de features según Fundamentos de Arquitectura Móvil.

Relacionado: Fundamentos de Expo Router - enrutamiento basado en archivos en SDK 57

Receta

Tarjeta de referencia rápida de stack para un B2C SaaS greenfield en SDK 57.

npx create-expo-app@latest AcmeSaaS --template default@sdk-57
cd AcmeSaaS
npx expo install @tanstack/react-query expo-secure-store react-native-mmkv
eas build:configure

// eas.json (fragmento) - profile → channel → environment
{
  "build": {
    "development": { "developmentClient": true, "channel": "development" },
    "preview": { "distribution": "internal", "channel": "preview" },
    "production": { "channel": "production" }
  }
}

// app.config.ts (fragmento) - runtime vincula OTA a la versión de store
export default {
  version: "2.4.0",
  runtimeVersion: { policy: "appVersion" },
  updates: { url: "https://u.expo.dev/<project-id>" },
};

Cuándo encaja esta referencia: Aplicaciones de consumidor por suscripción con pestañas con puerta de auth, backends REST y trenes de lanzamiento gestionados por EAS.

Cuándo divergir: Colas de mutación offline, datos regulados o shells nativos brownfield - consulta casos de estudio hermanos en esta sección.

Decisiones Tomadas

Alternativas rechazadas:

• Redux para caché del servidor - capacidades Query duplicadas; el equipo estandarizó en Query en la segunda semana.
• Expo Go para aprobación de QA - clientes dev de preview en dispositivos físicos reemplazaron Go antes del primer envío a store.
• OTA en cada commit - las actualizaciones de producción requieren soak de preview y publicación de CI según las reglas de lanzamiento Tier 2.

Resultados

Después de doce semanas en SDK 57 (migrado desde SDK 54 durante sprint cero - consulta Antes/Después: Actualización Principal de Expo SDK):

La ruta modal de paywall (presentation: "modal") se envió sin cambios de JSX de navegador - el producto podría hacer A/B de parámetros SKU a través de OTA mientras que la configuración nativa de StoreKit se mantuvo estable.

Lecciones

1. Fija SDK 57 en la narrativa y en package.json. Las notas de actualización pertenecen a ADRs; los casos de estudio sin fijaciones de versión envejecen mal - anota cada diagrama de arquitectura con el SDK que lo moldeó.

2. Rutas finas, features gordas. La mayor rotación fue src/features/inbox/, no app/(app)/(tabs)/inbox.tsx. La incorporación mejoró cuando los nuevos ingenieros aprendieron el sistema de archivos solo para URLs.

3. Los canales son ambientes, no ingenieros. Cambiar el nombre de jane-dev a preview eliminó publicaciones accidentales de OTA de producción.

4. staleTime de Query es un botón de producto. Inbox a 30s obsoleto, configuración a 5m - un staleTime global causó drenaje de batería innecesario.

5. Reconstruye clientes de dev después de bumps que afecten nativos. SDK 57 Reanimated y actualizaciones de expo-image requirieron nuevos binarios de perfil development; las actualizaciones solo de Metro mintieron sobre el comportamiento nativo.

6. Documenta lo que OTA no puede cambiar. Marketing una vez solicitó un nuevo permiso de cámara a través de OTA - bloqueado hasta la compilación de store; ahora listado en la lista de verificación de lanzamiento Tier 1.

Relacionado

• Fundamentos de Expo Router - grupos de rutas y layouts
• TanStack Query - caché de estado del servidor
• Fundamentos de EAS Build - perfiles y primera compilación en la nube
• expo-updates (Client API) - verificar, obtener, recargar
• Reglas de Lanzamiento y OTA - política de canal y runtime
• Ciclo de Vida de Sesión de Auth - actualización en primer plano
• Antes/Después: React Navigation - Expo Router - si migras un shell SaaS existente

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