# Argent React Native App Workflow > Flujos paso a paso para desarrollar o depurar apps React Native en simulador iOS o emulador Android. Úsalo para arrancar la app, depurar Metro, arreglar builds, diagnosticar errores en tiempo de ejecución o ejecutar tests. Fuente: https://skillsagentes.com/skills/software-mansion/argent/argent-react-native-app-workflow Markdown: https://skillsagentes.com/skills/software-mansion/argent/argent-react-native-app-workflow.md Repositorio: https://github.com/software-mansion/argent Autor: software-mansion Licencia: Apache-2.0 Actualizado: hace 14 días Coste de contexto: 53 tok instalada, 5.2k tok al activarse, 5.2k tok con todos los archivos del bundle Bundle: 1 archivo, 20 KB Permisos que pide: ninguno declarado ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add software-mansion/argent --skill argent-react-native-app-workflow --agent claude-code # Cursor npx -y skills add software-mansion/argent --skill argent-react-native-app-workflow --agent cursor # Codex npx -y skills add software-mansion/argent --skill argent-react-native-app-workflow --agent codex # Gemini CLI npx -y skills add software-mansion/argent --skill argent-react-native-app-workflow --agent gemini # Windsurf npx -y skills add software-mansion/argent --skill argent-react-native-app-workflow --agent windsurf # Cline npx -y skills add software-mansion/argent --skill argent-react-native-app-workflow --agent cline ``` ## Qué hace - Guía cómo arrancar Metro y la app respetando los scripts personalizados del proyecto antes de usar comandos por defecto - Diagnostica conflictos de puerto en Metro y confirma si el proceso que lo ocupa es realmente Metro - Explica cuándo recargar el bundle frente a reconstruir la app nativa según qué haya cambiado - Da el orden de pasos para arreglar builds fallidos: limpiar, reinstalar dependencias, reinstalar CocoaPods, abrir Xcode - Indica dónde mirar ante errores en tiempo de ejecución: logs JS, árbol de componentes React, logs nativos ## Cuándo usarla - Hay que arrancar la app React Native en simulador iOS o emulador Android - Se necesita depurar Metro o arreglar un build que falla - Hay errores en tiempo de ejecución que diagnosticar - Se van a ejecutar tests (Jest, Detox) del proyecto ## Qué la activa - "Arranca Metro y la app React Native en el simulador" - "El build de iOS está fallando, ayúdame a arreglarlo" - "Ejecuta los tests de la app" ## Antes de instalar - Necesita node_modules instalado y, en iOS, los Pods de CocoaPods actualizados (ios/Podfile). - Necesita en el PATH: npx ## Archivos - SKILL.md — 20 KB ## SKILL.md Reproducido tal cual desde software-mansion/argent bajo Apache-2.0. Esta sección es el documento original y está en inglés. ## 1. Starting the React Native App ### 1.1 Explore Configuration (MANDATORY — Do This First) **Before running commands**, read the project's build and run configuration from the `argent-environment-inspector` subagent result. Do NOT default to `npx react-native start` or `npx react-native run-ios` without first checking for custom scripts and workflows. **Manual fallback** (if neither the agent nor the tool is available): read ALL `package.json` scripts — look for custom scripts like `start:local`, `start:dev`, `ios`, `build:ios`, flavors, etc. Custom scripts take priority over default commands. Also check `metro.config.js` for non-default port or watchFolders. For iOS builds, prefer opening `.xcworkspace` over `.xcodeproj` (CocoaPods generates the workspace). **If the project structure is convoluted, ask the user before proceeding.** **Remember the workflow:** Once you discover the project's build/run workflow, save it to project memory so you don't need to re-discover it each time. **Checklist before start:** - [ ] `node_modules` present (if not: `npm install` or `yarn`) - [ ] For iOS: `ios/Podfile` exists; if `ios/Pods` missing or stale, run `cd ios && pod install && cd ..` - [ ] No conflicting Metro on default port (see 1.2) ### 1.2 Start Metro 1. Check whether metro is already running on port found in configuration and if it is - do not start another server. Refer to point 2.1. 1. **Use the project's custom start script if one exists** (e.g. `npm run start:local`, `yarn start:dev`). Fall back to default commands if no custom scripts are defined: ```bash npx react-native start ``` Optional: `npx react-native start --reset-cache` if cache issues are suspected. 1. **Verify Metro is ready**: use the `debugger-status` tool. It returns a `status` result instead of erroring: `status: "connected"` or `status: "not_connected"` with `reason: "no_app_connected"` both mean Metro is up (the app just hasn't attached yet); `reason: "metro_not_running"` means Metro is not reachable — follow the result's `guidance`. 1. **Projects with flavors or custom configs**: Use project-specific start script if present (e.g. `npm run start:local`), and start Metro **before** running the app. ### 1.3 Run the App In a **separate** terminal (Metro keeps running in the first): **Use the project's custom build/run script if one exists** (e.g. `npm run ios`, `npm run android`, `yarn ios:debug`). Only fall back to the defaults below if no custom scripts are defined. **Pass the target device explicitly** — derive it from `list-devices` (see ``): ```bash npx react-native run-ios --simulator="" # iOS (or --udid ) npx react-native run-android --deviceId= # Android ``` **Android only**: after install, run `adb -s reverse tcp:8081 tcp:8081` so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops. **Agent checklist:** - [ ] Metro is already running and shows "ready" - [ ] Command run from project root - [ ] If the device isn't booted yet: use `boot-device` with the iOS `udid` or Android `avdName`. Refer to the `argent-ios-simulator-setup` / `argent-android-emulator-setup` skill. - [ ] Android: `adb -s reverse tcp:8081 tcp:8081` done. --- ## 2. Ensuring / Debugging Metro ### 2.1 Check for Existing Metro Before starting Metro, avoid "port already in use" errors. Default port to check is :8081, infer the port from documentation: ```bash lsof -i :PORT ``` - **No output** → Port free; safe to start Metro. - **Output with PID** → Another process is using the port. Use the `debugger-status` tool to check whether the process on that port is actually a Metro server — it returns a structured result, not an error. `status: "connected"` or `reason: "no_app_connected"` → the process is Metro. `reason: "metro_not_running"` while `lsof` shows a listener → the port is occupied by something that is **not** Metro; the result's `detail` field shows what the process answered (`Metro at port ... is not running (got: ...)`). In that case ask the user whether you may kill the process. To kill a Metro process, use the `stop-metro` tool (requires user confirmation). ### 2.2 Confirm Correct Server Connection - **App must point at the same host/port as the running Metro.** Default: same machine, port 8081. - **iOS Simulator:** By default uses localhost; no extra config needed for same-machine Metro. **Verify Metro is reachable:** use the `debugger-status` tool. `reason: "metro_not_running"` means Metro did not answer on that port — start it (§2.1); `"no_app_connected"` means Metro answered but the app has not attached (§2.3). Any other reason: follow the result's `guidance` (it does not by itself prove Metro is up). ### 2.3 Reload the App (Ensure New Bundle) After code or config changes, the app must load the new bundle: | Method | How | | ----------- | ------------------------------------------------------------------------------------------------- | | Reload tool | Use the `debugger-reload-metro` tool | | Restart app | Use the `restart-app` tool, or kill the app in simulator and run `npx react-native run-ios` again | **Agent checklist:** - [ ] Only one Metro process (no duplicate on port) - [ ] App was started after Metro was ready - [ ] When needing to reload: refer to 2.3 --- ## 3. Build / Install / Retry (React Native & iOS Native) ### 3.1 When Build Fails (e.g. xcodebuild exit code 65) **Order of operations (simplest first):** 1. Clean build folder, then retry the build command 2. Clear caches and reinstall dependencies: reset Metro cache, `watchman watch-del-all`, remove `node_modules` + lockfile, `npm install`, then `cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update` 3. CocoaPods issues: `pod deintegrate` then `pod install --repo-update` 4. Open `ios/*.xcworkspace` in Xcode for detailed errors in the Report navigator ### 3.2 When to Ask the User **After 2-3 failed build or run attempts, STOP and ask the user for guidance.** The user may know about required env vars, Xcode version requirements, custom build configurations, monorepo-specific setup, or required external services. If the project structure is convoluted and the correct build approach is not obvious, **ask the user early** rather than guessing. ### 3.3 Saving Build Workflow for Later Once you discover the correct build/run workflow for a project, **save it to project memory**. Capture: commands to start Metro, commands to build/run the app, and any required environment setup. ### 3.4 When to Reinstall vs Refresh | Situation | Action | | ----------------------------------------------------- | ------------------------------------------------------------------------------------- | | JS/React only changed | Use `debugger-reload-metro` tool. No rebuild. | | Native code or `pod install` / project config changed | Rebuild: `npx react-native run-ios` (Metro can stay running). | | `node_modules` or `package.json` changed | `npm install`, then if native deps changed run `cd ios && pod install`. Then rebuild. | | App needs reinstalling from .app path | Use `reinstall-app` tool with UDID, bundle ID, and .app path. | | Persistent native build errors | Full clean + reinstall (step 2 above). | ### 3.5 Device Control | Action | Tool / Command | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | List devices | `list-devices` tool (iOS + Android) | | Boot an iOS simulator | `boot-device` tool with `udid` | | Boot an Android emulator | `boot-device` tool with `avdName` | | Launch an app | `launch-app` tool (pass device id + bundle id / package name) | | Restart an app | `restart-app` tool (pass device id + bundle id / package name) | | Open a URL / deep link | `open-url` tool (pass device id + URL) | | Rotate device | `rotate` tool | | Stop simulator server | `stop-simulator-server` tool (iOS UDID or Android serial — one device) | | Stop all simulator servers | `stop-all-simulator-servers` tool — pass `devices: [...]` to scope the teardown to this session's devices (an unscoped call also tears down other agents' devices; use it only for a machine-wide cleanup) | For full simulator setup workflow, refer to the `argent-ios-simulator-setup` skill. --- ## 4. Runtime Problems in the App ### 4.1 Where to Look | Problem type | Tool / Where to look | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **JavaScript errors / logs** | Use `debugger-log-registry` to get a summary and log file path, then `Grep`/`Read` to search. If it returns `status: "not_connected"`, no log file is returned — follow its `guidance` to reconnect first. | | **React component hierarchy** | Use `debugger-component-tree` tool for a text tree, or `debugger-inspect-element` at specific logical pixel coordinates (not normalized 0-1). | | **Visual state of the app** | Use `screenshot` tool to capture the current screen, but prefer `describe` or `debugger-component-tree` for actual navigation and target discovery. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to `screenshot`. | | **Evaluate JS in the app** | Use `debugger-evaluate` tool to run JavaScript in the app's runtime. | | **Native crashes / native stack** | `npx react-native log-ios` or iOS Simulator: Debug → Open System Log. | | **Build/runtime config** | `metro.config.js`, `babel.config.js`, `package.json` scripts, `ios/Podfile`. | For comprehensive Metro debugging workflows (component inspection, console logs, JS evaluation), refer to the `argent-metro-debugger` skill. ### 4.2 JS Console Logs (Log Registry) Logs are written to a flat log file on disk under `~/.argent/tmp/`. Use the **log-registry → grep** pattern instead of reading logs inline. For the full workflow, flat entry format, and grep examples, see `argent-metro-debugger` skill §5. ### 4.3 Do not try to use the DevMenu in React Native apps by default. Use the argent tools instead. --- ## 5. Testing the App Check the `argent-environment-inspector` result for test commands. For interactive UI testing with automatic screenshot verification, use the `argent-test-ui-flow` skill. - **Unit tests**: Look for Jest in `package.json` (`"test": "jest"`, `jest` config). Run: `npm test` or `yarn test`. - **E2E**: Look for Detox (`.detoxrc.js` or similar), or other E2E config. Dependencies: `detox`, `detox-cli`, and for iOS often `applesimutils`. - **Visible UI changes**: Use `argent-test-ui-flow` for manual QA. For `screenshot-diff` rules and parameters, follow the `argent-screenshot-diff` skill. Use it when stable before/after screenshots add meaningful pixel-visible evidence. - **UI flow testing**: For interactive UI testing with automatic screenshot verification, refer to the `argent-test-ui-flow` skill. ### 5.2 Running Tests (Typical) If the user's intent is ambiguous (run existing tests, write new tests, or find missing coverage), clarify before proceeding. - **Jest**: `npm test` or `npx jest`. - **Detox (example)**: - Build: `detox build --configuration ios.sim.release` (or debug). - Run: `detox test --configuration ios.sim.release`. - Ensure simulator is booted and not used by another process. ### 5.3 Agent Testing Checklist - [ ] Read `package.json` and test config (Jest, Detox, etc.). - [ ] If E2E: confirm simulator/device and build config. - [ ] If unclear: clarify whether to use existing workflows or write new tests. --- ## Quick Reference: Tools & Commands | Goal | Tool / Command | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Check port 8081 | `lsof -i :8081` | | Kill Metro | `stop-metro` tool | | Start Metro | `npx react-native start` | | Start Metro (reset cache) | `npx react-native start --reset-cache` | | Run iOS app | `npx react-native run-ios` | | Run Android app | `npx react-native run-android` | | List devices | `list-devices` tool (iOS + Android) | | Boot a device | `boot-device` tool (pass `udid` for iOS or `avdName` for Android) | | Take screenshot | `screenshot` tool | | Compare visible UI changes | `screenshot-diff` tool; follow the `argent-screenshot-diff` skill for baseline/current capture choices | | Describe screen (a11y tree) | `describe` tool for normal app screens and in-app modals; use `screenshot` only when permission/system overlays are not exposed reliably | | Read JS console logs | `debugger-log-registry` tool | | Reload JS bundle | `debugger-reload-metro` tool | | Check Metro status | `debugger-status` tool | | Inspect React component tree | `debugger-component-tree` tool | | Run JS in app | `debugger-evaluate` tool | | iOS native logs | `npx react-native log-ios` | | Android native logs | `npx react-native log-android` or `adb -s logcat` | | Clean + reinstall (nuclear) | See §3.1 step 3 | --- ## Related Skills | Skill | When to use | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `argent-ios-simulator-setup` | Initial iOS simulator boot and connection setup | | `argent-android-emulator-setup` | Initial Android emulator boot and connection setup | | `argent-device-interact` | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator | | `argent-metro-debugger` | JS-runtime CDP debugging (Metro on iOS / Android; the four ported tools also drive Chromium/CDP apps): component inspection, console logs, JS evaluation | | `argent-react-native-profiler` | Profiling performance, finding re-render issues, CPU hotspots | | `argent-test-ui-flow` | Interactive UI testing with automatic screenshot verification after each action | Ask the user before running tests: confirm which test suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself. ## Dónde encaja - Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código. - Creador: [software-mansion](https://skillsagentes.com/creators/software-mansion.md) — 0 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Argent Create Flow](https://skillsagentes.com/skills/software-mansion/argent/argent-create-flow.md): Crea, graba, edita, repite o repara flujos YAML reutilizables de Argent. Úsalo para grabar/repetir un recorrido de dispositivo, montar perfiles o comparaciones A/B, o antes de repetir tres o más interacciones. - [Argent Device Interact](https://skillsagentes.com/skills/software-mansion/argent/argent-device-interact.md): Interactúa con un simulador iOS, un emulador Android o una app Chromium (CDP) con las herramientas MCP de argent: toques, gestos, scroll, texto, botones físicos, lanzar apps, abrir URLs, capturas y esperas de elementos. - [Argent Test Ui Flow](https://skillsagentes.com/skills/software-mansion/argent/argent-test-ui-flow.md): Prueba de forma autónoma la interfaz de una app (iOS o Android) con bucles de interactuar-capturar-verificar usando las herramientas MCP de argent, para flujos de UI, login, navegación o pruebas end-to-end. - [Argent Metro Debugger](https://skillsagentes.com/skills/software-mansion/argent/argent-metro-debugger.md): Depura un runtime JS vía CDP con las herramientas de debugger de argent. La vía principal es React Native por Metro (iOS/Android/Vega); un subconjunto también controla el renderer de una app Chromium (CDP). - [Argent Qa Flows](https://skillsagentes.com/skills/software-mansion/argent/argent-qa-flows.md): Crea tests E2E de regresión QA reproducibles como flujos Argent a partir de casos de prueba, tickets o criterios de aceptación, con configuración determinista y dos pasadas consecutivas exitosas. Cubre iOS, Android, Chromium y Vega. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)