Expo

Esta página reúne lo que es específico de Expo: por qué hace falta un development build, cómo convive el agente con expo-router, cómo se nombran las rutas y qué no se puede hacer todavía.

Para instalar paso a paso, sigue Instalación en Expo. Aquí está la explicación de fondo y la lista de límites.

Todo lo que sigue se verificó en un proyecto nuevo de Expo SDK 57, con React Native 0.86 y expo-router, en el simulador de iOS y en el emulador de Android.

Expo funciona en las dos plataformas. En Android, con un development build, el agente se conecta, la pantalla se lee y las rutas de expo-router se reconocen.

Requisitos

• Un development build. No funciona en Expo Go.
• Los proyectos nativos generados, con npx expo prebuild.
• Node 22 o posterior para el CLI.
• Un simulador de iOS o un emulador de Android. Los dispositivos físicos no están soportados.

No hace falta un config plugin. El módulo nativo se enlaza automáticamente al compilar.

Por qué no funciona en Expo Go

El agente tiene código nativo: es lo que genera los toques y las teclas dentro del proceso. Expo Go es una app ya compilada que no puede incorporar módulos nativos nuevos. Un development build es tu propia app compilada en modo de depuración, y sí los incluye.

En la práctica, el ciclo es este:

npx expo install lynkeus-agent
npx lynkeus init
npx expo run:ios

o npx expo run:android. Solo hay que recompilar cuando cambia el código nativo, es decir, al instalar o actualizar lynkeus-agent.

El punto de entrada

El agente se monta antes de que la app renderice. En un proyecto con expo-router no hay un index.js propio donde hacerlo, porque el punto de entrada es el del enrutador.

La solución es darle a la app un archivo de entrada propio, que monte el agente y después cargue el enrutador. lynkeus init lo escribe y apunta main a él:

npx lynkeus init

Desde 0.3.0

lynkeus init existe desde la versión 0.3.0. Con una versión anterior, haz los dos cambios a mano.

El archivo que escribe es este:

index.js

import { auto } from 'lynkeus-agent/auto';

// Primero el agente, después el enrutador.
auto({ token: process.env.EXPO_PUBLIC_LYNKEUS_TOKEN });

import 'expo-router/entry';

Y este es el cambio en package.json:

package.json

{
  "main": "index.js"
}

No hay que modificar ningún _layout ni ninguna pantalla.

El token, en dos variables

El token es el secreto que comparten la app y el CLI. En Expo se llama distinto en cada lado, y la razón es una regla de Expo, no de lynkeus.

Expo solo incluye en el bundle las variables de entorno cuyo nombre empieza con EXPO_PUBLIC_. Una variable llamada LYNKEUS_TOKEN llegaría a la app como undefined.

Quién lo lee	Variable
La app, dentro del bundle	EXPO_PUBLIC_LYNKEUS_TOKEN
El CLI, en tu terminal	LYNKEUS_TOKEN

Las dos deben tener el mismo valor. Arranca el servidor de desarrollo con EXPO_PUBLIC_LYNKEUS_TOKEN ya definida.

Una app de React Native CLI recibe el token por el plugin de Babel lynkeus-agent/babel. Expo no lo necesita: incorpora la variable al bundle por su cuenta.

Precaución

Si la app recibe el token vacío o undefined, el agente queda apagado y la app lo dice en su log: lynkeus: the app passed a token and it is empty. No pasa a atender sin token. Comprueba que el nombre de la variable empiece con EXPO_PUBLIC_ y que esté definida donde arranca el servidor de desarrollo.

Desde 0.3.0

Antes de la versión 0.3.0, un token vacío se trataba como “sin token” y el agente atendía a cualquier proceso que se conectara.

Las rutas

El agente reconoce las rutas de expo-router sin configuración. En un proyecto nuevo, lynkeus screen imprime en su primera línea:

index (__root > index)

index es la ruta enfocada y __root > index es la cadena de navegadores hasta ella.

Los nombres van en minúscula

expo-router nombra cada ruta por su archivo, y por eso van en minúscula: index, explore. Esto importa en dos comandos.

lynkeus wait y lynkeus see reciben un solo argumento y deciden por su forma si es una ruta o un texto. Una palabra que empieza con mayúscula, como Settings.Main, se lee como ruta. Una palabra en minúscula sola se busca como texto en pantalla.

Para decir que una palabra en minúscula es una ruta, ponle adelante el prefijo route::

npx lynkeus wait route:index
npx lynkeus see route:index

En un caso, entre comillas:

steps:
  - app.wait: "route:index"

Desde 0.3.0

El prefijo route: existe desde la versión 0.3.0.

lynkeus nav no necesita el prefijo: su argumento siempre es una ruta.

npx lynkeus nav index

Límites conocidos

La barra de pestañas nativa

La plantilla más reciente de Expo usa una barra de pestañas nativa. La dibuja el sistema operativo, no React Native.

lynkeus lee el árbol de React, así que esas pestañas no aparecen como elementos en lynkeus screen y no se pueden tocar por nombre ni por testID.

Para cambiar de pestaña, navega a la ruta:

npx lynkeus nav <ruta>

En un caso:

steps:
  - app.nav: <ruta>

Ten presente lo que esto implica para tus tests. nav es un salto directo, no una acción de usuario, así que un caso escrito de este modo no demuestra que tocar la pestaña funcione. Demuestra lo que ocurre una vez que estás en ella.

Si tu app usa una barra de pestañas dibujada con componentes de React Native, este límite no aplica.

El host sin pantalla, con expo-router

Una app con expo-router no puede correr en el host sin pantalla. Ese host renderiza el componente raíz que la app exporta, y una app con expo-router no tiene ninguno: sus pantallas son archivos que carga el enrutador. lynkeus headless init se detiene con no App component found.

Una app así corre en un simulador o en un emulador.

Expo Go

No hay forma de usar lynkeus en Expo Go, por lo explicado arriba.

Builds de producción

Como en cualquier app de React Native, el agente solo existe en builds de depuración. Los detalles por sistema están en iOS y Android.

Próximos pasos

• Instalación en Expo, si todavía no instalaste.
• Tu primer test
• Solución de problemas