鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

argent-react-native-app-workflow

提供 React Native 应用在 iOS 模拟器或 Android 模拟器上的端到端开发与调试能力,覆盖启动流程、Metro 服务管理、构建安装排错、原生与 JS 运行时问题诊断、日志与组件树检查、截图比对及单元与 E2E 测试执行。

访问 GitHub
文档Skills.MD
name
argent-react-native-app-workflow
description
Step-by-step workflows for developing or debugging React Native apps on iOS simulator or Android emulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests.

Physical iPhone (kind: "device"): Metro debugging and profiling tools reject it. Use a simulator.

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.

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

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

  4. 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 <device_selection_rule>):

▼
bash
复制代码
npx react-native run-ios --simulator="<name>" # iOS (or --udid <UDID>) npx react-native run-android --deviceId=<adb-serial> # Android

Android only: after install, run adb -s <serial> 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 <serial> 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:

MethodHow
Reload toolUse the debugger-reload-metro tool
Restart appUse 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

SituationAction
JS/React only changedUse debugger-reload-metro tool. No rebuild.
Native code or pod install / project config changedRebuild: npx react-native run-ios (Metro can stay running).
node_modules or package.json changednpm install, then if native deps changed run cd ios && pod install. Then rebuild.
App needs reinstalling from .app pathUse reinstall-app tool with UDID, bundle ID, and .app path.
Persistent native build errorsFull clean + reinstall (step 2 above).

3.5 Device Control

ActionTool / Command
List deviceslist-devices tool (iOS + Android)
Boot an iOS simulatorboot-device tool with udid
Boot an Android emulatorboot-device tool with avdName
Launch an applaunch-app tool (pass device id + bundle id / package name)
Restart an apprestart-app tool (pass device id + bundle id / package name)
Open a URL / deep linkopen-url tool (pass device id + URL)
Rotate devicerotate tool
Stop simulator serverstop-simulator-server tool (iOS UDID or Android serial, one device)
Stop all simulator serversstop-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 typeTool / Where to look
JavaScript errors / logsUse debugger-log-registry to get a summary and log file path, then Grep to search. If it returns status: "not_connected", no log file is returned; follow its guidance to reconnect first.
React component hierarchyUse 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 appUse 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 appUse debugger-evaluate tool to run JavaScript in the app's runtime.
Native crashes / native stacknpx react-native log-ios or iOS Simulator: Debug → Open System Log.
Build/runtime configmetro.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

GoalTool / Command
Check port 8081lsof -i :8081
Kill Metrostop-metro tool
Start Metronpx react-native start
Start Metro (reset cache)npx react-native start --reset-cache
Run iOS appnpx react-native run-ios
Run Android appnpx react-native run-android
List deviceslist-devices tool (iOS + Android)
Boot a deviceboot-device tool (pass udid for iOS or avdName for Android)
Take screenshotscreenshot tool
Compare visible UI changesscreenshot-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 logsdebugger-log-registry tool
Reload JS bundledebugger-reload-metro tool
Check Metro statusdebugger-status tool
Inspect React component treedebugger-component-tree tool
Run JS in appdebugger-evaluate tool
iOS native logsnpx react-native log-ios
Android native logsnpx react-native log-android or adb -s <serial> logcat
Clean + reinstall (nuclear)See §3.1 step 3

Related Skills

SkillWhen to use
argent-ios-simulator-setupInitial iOS simulator boot and connection setup
argent-android-emulator-setupInitial Android emulator boot and connection setup
argent-device-interactTapping, swiping, typing, hardware buttons, gestures on the simulator/emulator
argent-metro-debuggerJS-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-profilerProfiling performance, finding re-render issues, CPU hotspots
argent-test-ui-flowInteractive 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.

快捷安装

复制到终端去安装 Skill

npxskillsaddhttps://github.com/software-mansion/argent--skillargent-react-native-app-workflow
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
lean-build
以极简方式构建高风险功能,强调架构一致性、范围严格控制与明确终止条件,通过复用现有接口、消除冗余逻辑、剔除非必要抽象与配置,实现端到端可验证的窄口径交付。
ast-grep
提供基于抽象语法树的结构化代码搜索能力,支持跨语言精准匹配代码模式、定位特定语法结构、识别复杂代码特征,适用于需理解代码语义而非简单文本匹配的深度代码分析场景。